././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9881895
coverage-7.11.0/ 0000755 0001751 0001751 00000000000 15073731560 013050 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.editorconfig 0000644 0001751 0001751 00000001560 15073731535 015531 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
# This file is for unifying the coding style for different editors and IDEs.
# More information at http://EditorConfig.org
root = true
[*]
charset = utf-8
end_of_line = lf
indent_size = 4
indent_style = space
insert_final_newline = true
max_line_length = 80
trim_trailing_whitespace = true
[*.py]
max_line_length = 100
[*.pyi]
max_line_length = 100
[*.c]
max_line_length = 100
[*.h]
max_line_length = 100
[*.{yml,yaml}]
indent_size = 2
[*.rst]
max_line_length = 79
[*.tok]
trim_trailing_whitespace = false
[*_dos.tok]
end_of_line = crlf
[Makefile]
indent_style = tab
indent_size = 8
[*,cover]
trim_trailing_whitespace = false
[*.diff]
trim_trailing_whitespace = false
[.git/*]
trim_trailing_whitespace = false
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.git-blame-ignore-revs 0000644 0001751 0001751 00000002225 15073731535 017153 0 ustar 00runner runner # Commits to ignore when doing git-blame.
# 2023-01-05 style: use good style for annotated defaults parameters
78444f4c06df6a634fa67dd99ee7c07b6b633d9e
# 2023-01-06 style(perf): blacken lab/benchmark.py
bf6c12f5da54db7c5c0cc47cbf22c70f686e8236
# 2023-03-22 style: use double-quotes
16abd82b6e87753184e8308c4b2606ff3979f8d3
b7be64538aa480fce641349d3053e9a84862d571
# 2023-04-01 style: use double-quotes in JavaScript
b03ab92bae24c54f1d5a98baa3af6b9a18de4d36
# 2023-11-04 style: ruff format igor.py, setup.py, __main__.py
acb80450d7c033a6ea6e06eb2e74d3590c268435
# 2023-11-20 style: fr"" is better than rf"", for real
d8daa08b347fe6b7099c437b09d926eb999d0803
# 2023-12-02 style: check_coverage close parens should be on their own line
5d0b5d4464b84adb6389c8894c207a323edb2b2b
# 2024-02-27 style: fix COM812 Trailing comma missing
e4e238a9ed8f2ad2b9060247591b4c057c2953bf
# 2024-02-27 style: modernize type hints, a few more f-strings
401a63bf08bdfd780b662f64d2dfe3603f2584dd
# 2025-08-09 style: ruff check --fix --fixable=I001,Q000 coverage/*.py
a32cd74bc0aaf0714acaf37beb21c84cbe2ee3ff
# 2025-08-21 chore: `ruff format .`
82467f72306efdb207af09ace27b6b3ed4c7ad6f
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9281895
coverage-7.11.0/.github/ 0000755 0001751 0001751 00000000000 15073731560 014410 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/CODE_OF_CONDUCT.md 0000644 0001751 0001751 00000000540 15073731535 017210 0 ustar 00runner runner # Treat each other well
Everyone participating in the coverage.py project, and in particular in the
issue tracker, pull requests, and social media activity, is expected to treat
other people with respect and to follow the guidelines articulated in the
[Python Community Code of Conduct][psf_coc].
[psf_coc]: https://www.python.org/psf/codeofconduct/
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/FUNDING.yml 0000644 0001751 0001751 00000000047 15073731535 016230 0 ustar 00runner runner github: nedbat
tidelift: pypi/coverage
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9291894
coverage-7.11.0/.github/ISSUE_TEMPLATE/ 0000755 0001751 0001751 00000000000 15073731560 016573 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/ISSUE_TEMPLATE/bug_report.md 0000644 0001751 0001751 00000002237 15073731535 021273 0 ustar 00runner runner ---
name: Bug report
about: Report a problem with coverage.py
title: ''
labels: bug
assignees: ''
---
**Describe the bug**
A clear and concise description of the bug.
**To Reproduce**
How can we reproduce the problem? Please *be specific*. Don't link to a failing CI job. Think about the time it will take us to recreate your situation: the easier you make it, the more likely your issue will be addressed.
Answer the questions below:
1. What version of Python are you using?
1. What version of coverage.py shows the problem? The output of `coverage debug sys` is helpful.
1. What versions of what packages do you have installed? The output of `pip freeze` is helpful.
1. What code shows the problem? Give us a *specific commit* of a *specific repo* that we can check out. If you've already worked around the problem, please provide a commit before that fix.
1. What commands should we run to reproduce the problem? *Be specific*. Include everything, even `git clone`, `pip install`, and so on. Explain like we're five!
**Expected behavior**
A clear and concise description of what you expected to happen.
**Additional context**
Add any other context about the problem here.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/ISSUE_TEMPLATE/config.yml 0000644 0001751 0001751 00000001120 15073731535 020557 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
# https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository
blank_issues_enabled: false
contact_links:
- name: Frequently Asked Questions
url: https://coverage.readthedocs.io/en/latest/faq.html
about: Some common problems are described here.
- name: Tidelift security contact
url: https://tidelift.com/security
about: Please report security vulnerabilities here.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/ISSUE_TEMPLATE/feature_request.md 0000644 0001751 0001751 00000001114 15073731535 022317 0 ustar 00runner runner ---
name: Feature request
about: Suggest an idea for coverage.py
title: ''
labels: enhancement
assignees: ''
---
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Describe the solution you'd like**
A clear and concise description of what you want to happen.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
Add any other context about the feature request here.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/ISSUE_TEMPLATE/support.md 0000644 0001751 0001751 00000001221 15073731535 020627 0 ustar 00runner runner ---
name: Support request
about: Ask for help using coverage.py
title: ''
labels: support
assignees: ''
---
**Have you asked elsewhere?**
There are other good places to ask for help using coverage.py. These places let
other people suggest solutions, are more likely places for people to find your
question:
- [Stack Overflow](https://stackoverflow.com/questions/tagged/coverage.py)
- [discuss.python.org](https://discuss.python.org/search?q=coverage.py)
**Describe your situation**
Wherever you ask your question, be sure to explain:
- What you did
- What happened
- How that was different than what you wanted to happen
- What kind of help you need
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/SECURITY.md 0000644 0001751 0001751 00000000311 15073731535 016176 0 ustar 00runner runner # Security Disclosures
To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure with maintainers.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/dependabot.yml 0000644 0001751 0001751 00000001010 15073731535 017232 0 ustar 00runner runner # From:
# https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot
# Set update schedule for GitHub Actions
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
# Check for updates to GitHub Actions once a week
interval: "weekly"
day: "sunday"
groups:
action-dependencies:
patterns:
- "*"
commit-message:
prefix: "chore"
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9301894
coverage-7.11.0/.github/workflows/ 0000755 0001751 0001751 00000000000 15073731560 016445 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/workflows/codeql-analysis.yml 0000644 0001751 0001751 00000005315 15073731535 022266 0 ustar 00runner runner # For most projects, this workflow file will not need changing; you simply need
# to commit it to your repository.
#
# You may wish to alter this file to override the set of languages analyzed,
# or to provide custom queries or build logic.
#
# ******** NOTE ********
# We have attempted to detect the languages in your repository. Please check
# the `language` matrix defined below to confirm you have the correct set of
# supported CodeQL languages.
#
name: "CodeQL"
on:
push:
branches:
- master
pull_request:
# The branches below must be a subset of the branches above
branches:
- master
schedule:
- cron: '30 20 * * 6'
permissions:
contents: read
jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest
permissions:
actions: read # CodeQL wrote this action.
contents: read
security-events: write # CodeQL wrote this action.
strategy:
fail-fast: false
matrix:
language:
- python
- javascript
# CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
# Learn more about CodeQL language support at https://git.io/codeql-language-support
steps:
- name: Checkout repository
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@f443b600d91635bebf5b0d9ebc620189c0d6fba5 # v4.30.8
with:
languages: ${{ matrix.language }}
# If you wish to specify custom queries, you can do so here or in a config file.
# By default, queries listed here will override any specified in a config file.
# Prefix the list here with "+" to use these queries and those in the config file.
# queries: ./path/to/local/query, your-org/your-repo/queries@main
# Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
# If this step fails, then you should remove it and run the build manually (see below)
- name: Autobuild
uses: github/codeql-action/autobuild@f443b600d91635bebf5b0d9ebc620189c0d6fba5 # v4.30.8
# โน๏ธ Command-line programs to run using the OS shell.
# ๐ https://git.io/JvXDl
# โ๏ธ If the Autobuild fails above, remove it and uncomment the following three lines
# and modify them (or add more) to build your code if your project
# uses a compiled language
#- run: |
# make bootstrap
# make release
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@f443b600d91635bebf5b0d9ebc620189c0d6fba5 # v4.30.8
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/workflows/coverage.yml 0000644 0001751 0001751 00000024523 15073731535 020773 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
name: "Coverage"
on:
# As currently structured, this adds too many jobs (checks?), so don't run it
# on pull requests yet.
push:
branches:
- master
- "**/*metacov*"
workflow_dispatch:
defaults:
run:
shell: bash
env:
PIP_DISABLE_PIP_VERSION_CHECK: 1
COVERAGE_IGOR_VERBOSE: 1
FORCE_COLOR: 1 # Get colored pytest output
permissions:
contents: read
concurrency:
group: "${{ github.workflow }}-${{ github.ref }}"
cancel-in-progress: true
jobs:
changed:
name: "Check changed files"
runs-on: ubuntu-latest
permissions:
pull-requests: read # Needed for this check to run on pull requests
outputs:
run_coverage: ${{ steps.filter.outputs.run_coverage }}
workflow: ${{ steps.filter.outputs.workflow }}
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Examine changed files"
uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
id: filter
with:
filters: |
run_coverage:
- "*.py"
- "coverage/**.py"
- "tests/**.py"
- "**.h"
- "**.c"
- ".github/workflows/coverage.yml"
- "tox.ini"
- "metacov.ini"
- "requirements/*.pip"
- "tests/gold/**"
coverage:
name: "${{ matrix.python-version }} on ${{ matrix.os }}"
runs-on: "${{ matrix.os }}-${{ matrix.os-version || 'latest' }}"
timeout-minutes: 30
# Only run coverage if Python files or this workflow changed.
needs: changed
if: ${{ needs.changed.outputs.run_coverage == 'true' }}
env:
MATRIX_ID: "${{ matrix.python-version }}.${{ matrix.os }}"
TOX_GH_MAJOR_MINOR: "${{ matrix.python-version }}"
strategy:
matrix:
os:
- ubuntu
- macos
- windows
python-version:
# When changing this list, be sure to check the [gh] list in
# tox.ini so that tox will run properly. PYVERSIONS
# Available versions:
# https://github.com/actions/python-versions/blob/main/versions-manifest.json
- "3.10"
- "3.11"
- "3.12"
- "3.13"
- "3.13t"
- "3.14"
- "3.14t"
- "3.15"
- "3.15t"
- "pypy-3.10"
exclude:
# Mac PyPy always takes the longest, and doesn't add anything.
- os: macos
python-version: "pypy-3.10"
# Windows pypy 3.10 gets stuck with PyPy 7.3.15. I hope to
# unstick them, but I don't want that to block all other progress, so
# skip them for now.
- os: windows
python-version: "pypy-3.10"
# If we need to tweak the os version we can do it with an include like
# this:
# include:
# - python-version: "3.12"
# os: "macos"
# os-version: "15"
# If one job fails, stop the whole thing.
fail-fast: true
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Set up Python"
uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "${{ matrix.python-version }}"
allow-prereleases: true
# At a certain point, installing dependencies failed on pypy 3.9 and
# 3.10 on Windows. Commenting out the cache here fixed it. Someday
# try using the cache again.
#cache: pip
#cache-dependency-path: 'requirements/*.pip'
- name: "Show environment"
run: |
set -xe
echo matrix id: $MATRIX_ID
python -VV
python -m site
env | sort
- name: "Install dependencies"
run: |
set -xe
python -m pip install -r requirements/tox.pip
- name: "Run tox coverage for ${{ matrix.python-version }}"
env:
COVERAGE_COVERAGE: "yes"
COVERAGE_CONTEXT: "${{ env.MATRIX_ID }}"
run: |
set -xe
python -m tox
- name: "Combine data"
env:
COVERAGE_RCFILE: "metacov.ini"
run: |
python -m coverage combine
mv .metacov .metacov.$MATRIX_ID
- name: "Upload coverage data"
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: metacov-${{ env.MATRIX_ID }}
path: .metacov.*
include-hidden-files: true
combine:
name: "Combine coverage data"
needs: coverage
runs-on: ubuntu-latest
outputs:
total: ${{ steps.total.outputs.total }}
env:
COVERAGE_RCFILE: "metacov.ini"
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Set up Python"
uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "3.10" # Minimum of PYVERSIONS
# At a certain point, installing dependencies failed on pypy 3.9 and
# 3.10 on Windows. Commenting out the cache here fixed it. Someday
# try using the cache again.
#cache: pip
#cache-dependency-path: 'requirements/*.pip'
- name: "Show environment"
run: |
set -xe
python -VV
python -m site
env | sort
- name: "Install dependencies"
run: |
set -xe
python -m pip install -e .
python igor.py zip_mods
- name: "Download coverage data"
uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
with:
pattern: metacov-*
merge-multiple: true
- name: "Combine and report"
id: combine
env:
COVERAGE_CONTEXT: "yes"
run: |
set -xe
python igor.py combine_html
- name: "Upload HTML report"
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: html_report
path: htmlcov
include-hidden-files: true
- name: "Show text report"
run: |
set -xe
echo "## Coverage: $(python -m coverage report --format=total)%" >> $GITHUB_STEP_SUMMARY
echo '```' >> $GITHUB_STEP_SUMMARY
python -m coverage report --skip-covered >> $GITHUB_STEP_SUMMARY
echo '```' >> $GITHUB_STEP_SUMMARY
- name: "Get total"
id: total
run: |
echo "total=$(python -m coverage report --format=total)" >> $GITHUB_OUTPUT
publish:
name: "Publish coverage report"
needs: combine
runs-on: ubuntu-latest
steps:
- name: "Show environment"
run: |
set -xe
env | sort
- name: "Compute info for later steps"
id: info
env:
REF: ${{ github.ref }}
SHA: ${{ github.sha }}
run: |
export SHA10=$(echo $SHA | cut -c 1-10)
export SLUG=$(date +'%Y%m%d')_$SHA10
echo "sha10=$SHA10" >> $GITHUB_ENV
echo "slug=$SLUG" >> $GITHUB_ENV
echo "report_dir=reports/$SLUG/htmlcov" >> $GITHUB_ENV
echo "url=https://htmlpreview.github.io/?https://github.com/nedbat/coverage-reports/blob/main/reports/$SLUG/htmlcov/index.html" >> $GITHUB_ENV
echo "branch=${REF#refs/heads/}" >> $GITHUB_ENV
- name: "Checkout reports repo"
if: ${{ github.ref == 'refs/heads/master' }}
env:
TOKEN: ${{ secrets.COVERAGE_REPORTS_TOKEN }}
run: |
set -xe
git clone --depth=1 --no-checkout https://${TOKEN}@github.com/nedbat/coverage-reports reports_repo
cd reports_repo
git sparse-checkout init --cone
git sparse-checkout set --skip-checks '/*' '!/reports'
git config user.name nedbat
git config user.email ned@nedbatchelder.com
git checkout main
- name: "Download coverage HTML report"
if: ${{ github.ref == 'refs/heads/master' }}
uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
with:
name: html_report
path: reports_repo/${{ env.report_dir }}
- name: "Push to report repo"
if: |
github.repository_owner == 'nedbat'
&& github.ref == 'refs/heads/master'
env:
COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
TOTAL: ${{ needs.combine.outputs.total }}
run: |
set -xe
# Make the redirect to the latest report.
echo "" > reports_repo/latest.html
echo "" >> reports_repo/latest.html
echo "Coverage report redirect..." >> reports_repo/latest.html
# Make the commit message.
echo "${TOTAL}% - ${COMMIT_MESSAGE}" > commit.txt
echo "" >> commit.txt
echo "${url}" >> commit.txt
echo "${sha10}: ${branch}" >> commit.txt
# Commit.
cd ./reports_repo
git sparse-checkout set --skip-checks '/*' ${report_dir}
rm ${report_dir}/.gitignore
git add ${report_dir} latest.html
git commit --file=../commit.txt
git push
echo "[${url}](${url})" >> $GITHUB_STEP_SUMMARY
- name: "Create badge"
if: |
github.repository_owner == 'nedbat'
&& github.ref == 'refs/heads/master'
# https://gist.githubusercontent.com/nedbat/8c6980f77988a327348f9b02bbaf67f5
uses: schneegans/dynamic-badges-action@e9a478b16159b4d31420099ba146cdc50f134483 # v1.7.0
with:
auth: ${{ secrets.METACOV_GIST_SECRET }}
gistID: 8c6980f77988a327348f9b02bbaf67f5
filename: metacov.json
label: Coverage
message: ${{ needs.combine.outputs.total }}%
minColorRange: 60
maxColorRange: 95
valColorRange: ${{ needs.combine.outputs.total }}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/workflows/dependency-review.yml 0000644 0001751 0001751 00000002503 15073731535 022607 0 ustar 00runner runner # Dependency Review Action
#
# This Action will scan dependency manifest files that change as part of a Pull Reqest, surfacing known-vulnerable versions of the packages declared or updated in the PR. Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable packages will be blocked from merging.
#
# Source repository: https://github.com/actions/dependency-review-action
# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
name: 'Dependency Review'
on:
push:
branches:
- master
- nedbat/*
pull_request:
workflow_dispatch:
permissions:
contents: read
jobs:
dependency-review:
name: "Review dependencies"
if: github.repository_owner == 'nedbat'
runs-on: ubuntu-latest
steps:
- name: 'Checkout Repository'
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: 'Dependency Review'
uses: actions/dependency-review-action@40c09b7dc99638e5ddb0bfd91c1673effc064d8a # v4.8.1
with:
base-ref: ${{ github.event.pull_request.base.sha || 'master' }}
head-ref: ${{ github.event.pull_request.head.sha || github.ref }}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/workflows/kit.yml 0000644 0001751 0001751 00000027617 15073731535 017776 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
# This file is meant to be processed with cog.
# Running "make prebuild" will bring it up to date.
# Based on:
# https://github.com/joerick/cibuildwheel/blob/master/examples/github-deploy.yml
# To test installing wheels without uploading them to PyPI:
#
# $ mkdir /tmp/pypi
# $ cp dist/* /tmp/pypi
# $ python -m pip install piprepo
# $ piprepo build /tmp/pypi
# $ python -m pip install -v coverage --index-url=file:///tmp/pypi/simple
#
name: "Kits"
on:
push:
branches:
# Don't build kits all the time, but do if the branch is about kits.
- "**/*kit*"
workflow_dispatch:
repository_dispatch:
types:
- build-kits
defaults:
run:
shell: bash
env:
PIP_DISABLE_PIP_VERSION_CHECK: 1
# PYVERSIONS: changing the list of versions will change the number of
# expected distributions. This must match the same number in publish.yml.
EXPECTED: 92
permissions:
contents: read
concurrency:
group: "${{ github.workflow }}-${{ github.ref }}"
cancel-in-progress: true
jobs:
wheels:
name: "${{ matrix.py }} ${{ matrix.os }} ${{ matrix.arch }} wheels"
runs-on: "${{ matrix.os }}-${{ matrix.os-version || 'latest' }}"
env:
MATRIX_ID: "${{ matrix.py }}-${{ matrix.os }}-${{ matrix.arch }}"
strategy:
matrix:
include:
# To change the matrix, edit the choices, then process this file with cog:
#
# $ make workflows
#
# which runs:
#
# $ python -m pip install cogapp
# $ python -m cogapp -crP .github/workflows/kit.yml
#
# Choices come from the table on https://pypi.org/project/cibuildwheel/
#
# [[[cog
# #----- vvv Choices for the matrix vvv -----
#
# # Operating systems:
# oss = ["ubuntu", "macos", "windows"]
#
# # For each OS, what arch to use with cibuildwheel:
# os_archs = {
# "ubuntu": ["x86_64", "i686", "aarch64", "riscv64"],
# "macos": ["arm64", "x86_64"],
# "windows": ["x86", "AMD64", "ARM64"],
# }
# # PYVERSIONS. Available versions: https://pypi.org/project/cibuildwheel/
# # Note that cibuildwheel recommends not shipping wheels for pre-release versions
# # of Python: https://cibuildwheel.readthedocs.io/en/stable/options/#enable
# # When changing this, also adjust SHIPPING_WHEELS in env.py.
#
# pys = ["cp310", "cp311", "cp312", "cp313", "cp314"]
#
# # Some OS/arch combinations need overrides for the Python versions:
# os_arch_pys = {
# # ("macos", "arm64"): ["cp38", "cp39", "cp310", "cp311", "cp312"],
# ("windows", "ARM64"): ["cp311", "cp312", "cp313", "cp314"],
# }
#
# #----- ^^^ ---------------------- ^^^ -----
#
# import json
# for the_os in oss:
# for the_arch in os_archs[the_os]:
# for the_py in os_arch_pys.get((the_os, the_arch), pys):
# them = {
# "os": the_os,
# "py": the_py,
# "arch": the_arch,
# }
# if the_os == "macos":
# them["os-version"] = "13"
# if the_os == "windows" and the_arch == "ARM64":
# them["os-version"] = "11-arm"
# # them["minpy"] = "3.11"
# if the_arch == "aarch64":
# # https://github.com/pypa/cibuildwheel/issues/2257
# them["os-version"] = "22.04-arm"
# print(f"- {json.dumps(them)}")
# ]]]
- {"os": "ubuntu", "py": "cp310", "arch": "x86_64"}
- {"os": "ubuntu", "py": "cp311", "arch": "x86_64"}
- {"os": "ubuntu", "py": "cp312", "arch": "x86_64"}
- {"os": "ubuntu", "py": "cp313", "arch": "x86_64"}
- {"os": "ubuntu", "py": "cp314", "arch": "x86_64"}
- {"os": "ubuntu", "py": "cp310", "arch": "i686"}
- {"os": "ubuntu", "py": "cp311", "arch": "i686"}
- {"os": "ubuntu", "py": "cp312", "arch": "i686"}
- {"os": "ubuntu", "py": "cp313", "arch": "i686"}
- {"os": "ubuntu", "py": "cp314", "arch": "i686"}
- {"os": "ubuntu", "py": "cp310", "arch": "aarch64", "os-version": "22.04-arm"}
- {"os": "ubuntu", "py": "cp311", "arch": "aarch64", "os-version": "22.04-arm"}
- {"os": "ubuntu", "py": "cp312", "arch": "aarch64", "os-version": "22.04-arm"}
- {"os": "ubuntu", "py": "cp313", "arch": "aarch64", "os-version": "22.04-arm"}
- {"os": "ubuntu", "py": "cp314", "arch": "aarch64", "os-version": "22.04-arm"}
- {"os": "ubuntu", "py": "cp310", "arch": "riscv64"}
- {"os": "ubuntu", "py": "cp311", "arch": "riscv64"}
- {"os": "ubuntu", "py": "cp312", "arch": "riscv64"}
- {"os": "ubuntu", "py": "cp313", "arch": "riscv64"}
- {"os": "ubuntu", "py": "cp314", "arch": "riscv64"}
- {"os": "macos", "py": "cp310", "arch": "arm64", "os-version": "13"}
- {"os": "macos", "py": "cp311", "arch": "arm64", "os-version": "13"}
- {"os": "macos", "py": "cp312", "arch": "arm64", "os-version": "13"}
- {"os": "macos", "py": "cp313", "arch": "arm64", "os-version": "13"}
- {"os": "macos", "py": "cp314", "arch": "arm64", "os-version": "13"}
- {"os": "macos", "py": "cp310", "arch": "x86_64", "os-version": "13"}
- {"os": "macos", "py": "cp311", "arch": "x86_64", "os-version": "13"}
- {"os": "macos", "py": "cp312", "arch": "x86_64", "os-version": "13"}
- {"os": "macos", "py": "cp313", "arch": "x86_64", "os-version": "13"}
- {"os": "macos", "py": "cp314", "arch": "x86_64", "os-version": "13"}
- {"os": "windows", "py": "cp310", "arch": "x86"}
- {"os": "windows", "py": "cp311", "arch": "x86"}
- {"os": "windows", "py": "cp312", "arch": "x86"}
- {"os": "windows", "py": "cp313", "arch": "x86"}
- {"os": "windows", "py": "cp314", "arch": "x86"}
- {"os": "windows", "py": "cp310", "arch": "AMD64"}
- {"os": "windows", "py": "cp311", "arch": "AMD64"}
- {"os": "windows", "py": "cp312", "arch": "AMD64"}
- {"os": "windows", "py": "cp313", "arch": "AMD64"}
- {"os": "windows", "py": "cp314", "arch": "AMD64"}
- {"os": "windows", "py": "cp311", "arch": "ARM64", "os-version": "11-arm"}
- {"os": "windows", "py": "cp312", "arch": "ARM64", "os-version": "11-arm"}
- {"os": "windows", "py": "cp313", "arch": "ARM64", "os-version": "11-arm"}
- {"os": "windows", "py": "cp314", "arch": "ARM64", "os-version": "11-arm"}
# [[[end]]] (sum: 1z4k0aOD5S)
# ^^^^^^^^^^^^^^^
# If a check fails and points to this checksum line, it means you edited
# the matrix directly instead of editing the Python code in the comment
# above it. The matrix is generated by running cog as described at the
# top of that comment.
fail-fast: false
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Install Python"
uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "${{ matrix.minpy || '3.11' }}" # PYVERSIONS needed by cibuildwheel
cache: pip
cache-dependency-path: 'requirements/*.pip'
# Rust toolchain is not currently installed on windows arm64 images.
# We need it for nh3, needed by readme-renderer, needed by twine.
# https://github.com/actions/partner-runner-images/issues/77
- if: ${{ matrix.os-version == '11-arm' }}
name: Setup rust
id: setup-rust
shell: pwsh
run: |
Invoke-WebRequest https://static.rust-lang.org/rustup/dist/aarch64-pc-windows-msvc/rustup-init.exe -OutFile .\rustup-init.exe
.\rustup-init.exe -y
Add-Content $env:GITHUB_PATH "$env:USERPROFILE\.cargo\bin"
- name: "Install tools"
run: |
python -m pip install -r requirements/kit.pip
- name: Set up QEMU
if: ${{ matrix.arch == 'riscv64' }}
uses: docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392 # v3.6.0
- name: "Build binary wheels"
env:
CIBW_BUILD: ${{ matrix.py }}*-*
CIBW_ARCHS: ${{ matrix.arch }}
CIBW_ENVIRONMENT: PIP_DISABLE_PIP_VERSION_CHECK=1
CIBW_ENABLE: cpython-prerelease cpython-freethreading
CIBW_TEST_COMMAND: python -c "from coverage.tracer import CTracer; print('CTracer OK!')"
run: |
python -m cibuildwheel --output-dir wheelhouse
- name: "List binary wheels"
run: |
ls -al wheelhouse/
- name: "Check wheels"
run: |
python -m twine check wheelhouse/*
- name: "Upload binary wheels"
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: dist-${{ env.MATRIX_ID }}
path: wheelhouse/*.whl
retention-days: 7
non-binary:
name: "Non-binary artifacts"
runs-on: ubuntu-latest
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Install Python"
uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "3.11" # PYVERSIONS: the kit-building version
cache: pip
cache-dependency-path: 'requirements/*.pip'
- name: "Install tools"
run: |
python -m pip install -r requirements/kit.pip
- name: "Build non-binary artifacts"
env:
COVERAGE_DISABLE_EXTENSION: 1
run: |
python -m build
- name: "List non-binary artifacts"
run: |
ls -al dist/
- name: "Check non-binary artifacts"
run: |
python -m twine check dist/*
- name: "Upload non-binary artifacts"
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: dist-non-binary
path: dist/*
retention-days: 7
sign:
# This signs our artifacts, but we don't use the signatures for anything
# yet. Someday maybe PyPI will have a way to upload and verify them.
name: "Sign artifacts"
needs:
- wheels
- non-binary
runs-on: ubuntu-latest
permissions:
id-token: write # Needed for signing artifacts
steps:
- name: "Download artifacts"
uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
with:
pattern: dist-*
merge-multiple: true
- name: "List distributions"
run: |
ls -alR
echo "Number of dists, there should be $EXPECTED:"
ls -1 coverage-* | wc -l
files=$(ls coverage-* 2>/dev/null | wc -l) && [ "$files" -eq $EXPECTED ] || exit 1
- name: "Sign artifacts"
uses: sigstore/gh-action-sigstore-python@f7ad0af51a5648d09a20d00370f0a91c3bdf8f84 # v3.0.1
with:
inputs: coverage-*.*
- name: "List files"
run: |
ls -alR
- name: "Upload signatures"
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: signatures
path: "*.sigstore.json"
retention-days: 7
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/workflows/publish.yml 0000644 0001751 0001751 00000010256 15073731535 020644 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
name: "Publish"
on:
repository_dispatch:
# Triggered with `make` targets:
types:
- publish-testpypi # `make test_upload`
- publish-pypi # `make pypi_upload`
defaults:
run:
shell: bash
env:
# PYVERSIONS: changing the list of versions will change the number of
# expected distributions. This must match the same number in kit.yml.
EXPECTED: 92
permissions:
contents: read
concurrency:
group: "${{ github.workflow }}-${{ github.ref }}"
cancel-in-progress: true
jobs:
find-run:
name: "Find latest kit.yml run"
runs-on: "ubuntu-latest"
outputs:
run-id: ${{ steps.run-id.outputs.run-id }}
steps:
- name: "Find latest kit.yml run"
id: runs
uses: octokit/request-action@dad4362715b7fb2ddedf9772c8670824af564f0d # v2.4.0
with:
route: GET /repos/nedbat/coveragepy/actions/workflows/kit.yml/runs
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: "Record run id" # zizmor: ignore[template-injection]
id: run-id
run: |
# There must be a shorter way to write this...
[ "${{ fromJson(steps.runs.outputs.data).workflow_runs[0].status}}" = "completed" ] || exit 1
[ "${{ fromJson(steps.runs.outputs.data).workflow_runs[0].conclusion}}" = "success" ] || exit 1
echo "run-id=${{ fromJson(steps.runs.outputs.data).workflow_runs[0].id }}" >> "$GITHUB_OUTPUT"
publish-to-test-pypi:
name: "Publish to Test PyPI"
if: ${{ github.event.action == 'publish-testpypi' }}
permissions:
id-token: write # needed for actions/attest-build-provenance
attestations: write # needed for actions/attest-build-provenance
runs-on: "ubuntu-latest"
environment:
name: "testpypi"
needs:
- find-run
steps:
- name: "Download dists"
uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
with:
repository: "nedbat/coveragepy"
run-id: ${{ needs.find-run.outputs.run-id }}
github-token: ${{ secrets.GITHUB_TOKEN }}
pattern: "dist-*"
merge-multiple: true
path: "dist/"
- name: "What did we get?"
run: |
ls -alR
echo "Number of dists, should be $EXPECTED:"
ls -1 dist | wc -l
files=$(ls dist 2>/dev/null | wc -l) && [ "$files" -eq $EXPECTED ] || exit 1
- name: "Generate attestations"
uses: actions/attest-build-provenance@977bb373ede98d70efdf65b84cb5f73e068dcc2a # v3.0.0
with:
subject-path: "dist/*"
- name: "Publish dists to Test PyPI"
uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
with:
repository-url: https://test.pypi.org/legacy/
publish-to-pypi:
name: "Publish to PyPI"
if: ${{ github.event.action == 'publish-pypi' }}
permissions:
id-token: write # needed for actions/attest-build-provenance
attestations: write # needed for actions/attest-build-provenance
runs-on: "ubuntu-latest"
environment:
name: "pypi"
needs:
- find-run
steps:
- name: "Download dists"
uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
with:
repository: "nedbat/coveragepy"
run-id: ${{ needs.find-run.outputs.run-id }}
github-token: ${{ secrets.GITHUB_TOKEN }}
pattern: "dist-*"
merge-multiple: true
path: "dist/"
- name: "What did we get?"
run: |
ls -alR
echo "Number of dists, should be $EXPECTED:"
ls -1 dist | wc -l
files=$(ls dist 2>/dev/null | wc -l) && [ "$files" -eq $EXPECTED ] || exit 1
- name: "Generate attestations"
uses: actions/attest-build-provenance@977bb373ede98d70efdf65b84cb5f73e068dcc2a # v3.0.0
with:
subject-path: "dist/*"
- name: "Publish dists to PyPI"
uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/workflows/python-nightly.yml 0000644 0001751 0001751 00000006160 15073731535 022172 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
name: "Python Nightly Tests"
on:
push:
branches:
- "**/*nightly*"
schedule:
# Run at 2:22am early every morning Eastern time (6/7:22 UTC)
# so that we get tips of CPython development tested.
# https://crontab.guru/#22_7_%2a_%2a_%2a
- cron: "22 7 * * *"
workflow_dispatch:
defaults:
run:
shell: bash
env:
PIP_DISABLE_PIP_VERSION_CHECK: 1
COVERAGE_IGOR_VERBOSE: 1
permissions:
contents: read
concurrency:
group: "${{ github.workflow }}-${{ github.ref }}"
cancel-in-progress: true
jobs:
tests:
name: "${{ matrix.python-version }}"
runs-on: "${{ matrix.os }}"
# If it doesn't finish in an hour, it's not going to. Don't spin for six
# hours needlessly.
timeout-minutes: 60
env:
TOX_GH_MAJOR_MINOR: "${{ matrix.python-version }}"
strategy:
matrix:
os:
- "ubuntu-latest"
python-version:
# When changing this list, be sure to check the [gh] list in
# tox.ini so that tox will run properly. PYVERSIONS
- "3.13"
- "3.13t"
- "3.14"
- "3.14t"
- "3.15"
- "3.15t"
fail-fast: false
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Install system dependencies"
run: |
sudo sed -i.bak 's/^Types: deb$/Types: deb deb-src/' /etc/apt/sources.list.d/ubuntu.sources
sudo apt-get update
sudo apt-get build-dep -y python3
- name: "Install pyenv"
run: |
curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash
- name: "Build Python ${{ matrix.python-version }}-dev"
env:
PYVER: "${{ matrix.python-version }}-dev"
run: |
set -xe
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
echo "$PYENV_ROOT/shims:$PYENV_ROOT/bin" >> $GITHUB_PATH
pyenv install $PYVER -v
pyenv global $PYVER
- name: "Show diagnostic info"
run: |
set -xe
python -VV
python -m site
python -m sysconfig
python -c "import sys; print('GIL:', getattr(sys, '_is_gil_enabled', lambda: True)())"
python -m coverage debug sys
python -m coverage debug pybehave
env | sort
- name: "Check the Python version"
env:
EXPECTED: "${{ matrix.python-version }}"
run: |
python -c "
import sys
print(f'{sys.version = }')
assert sys.version.startswith('$EXPECTED'.strip('t'))
assert getattr(sys, '_is_gil_enabled', lambda: True)() == (not '$EXPECTED'.endswith('t'))
"
- name: "Install dependencies"
run: |
python -m pip install -r requirements/tox.pip
- name: "Run tox"
run: |
python -m tox -v -- -rfsEX
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/workflows/quality.yml 0000644 0001751 0001751 00000012054 15073731535 020664 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
name: "Quality"
on:
push:
branches:
- master
- nedbat/*
pull_request:
workflow_dispatch:
defaults:
run:
shell: bash
env:
PIP_DISABLE_PIP_VERSION_CHECK: 1
permissions:
contents: read
concurrency:
group: "${{ github.workflow }}-${{ github.ref }}"
cancel-in-progress: true
jobs:
changed:
name: "Check changed files"
runs-on: ubuntu-latest
permissions:
pull-requests: read # Needed for this check to run on pull requests
outputs:
python: ${{ steps.filter.outputs.python }}
docs: ${{ steps.filter.outputs.docs }}
actions: ${{ steps.filter.outputs.actions }}
workflow: ${{ steps.filter.outputs.workflow }}
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Examine changed files"
uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
id: filter
with:
filters: |
python:
- "**.py"
docs:
- "doc/**"
- "coverage/**.py"
actions:
- ".github/workflows/**"
workflow:
- ".github/workflows/quality.yml"
- "tox.ini"
- "requirements/*.pip"
lint:
name: "Pylint etc"
# Because pylint can report different things on different OS's (!)
# (https://github.com/PyCQA/pylint/issues/3489), run this on Mac where local
# pylint gets run.
runs-on: macos-latest
needs: changed
if: ${{ needs.changed.outputs.python == 'true' || needs.changed.outputs.actions == 'true' || needs.changed.outputs.workflow == 'true' }}
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Install Python"
uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "3.10" # Minimum of PYVERSIONS
cache: pip
cache-dependency-path: 'requirements/*.pip'
- name: "Install dependencies"
run: |
python -m pip install -r requirements/tox.pip
- name: "Tox lint"
run: |
python -m tox -e lint
mypy:
name: "Check types"
runs-on: ubuntu-latest
needs: changed
if: ${{ needs.changed.outputs.python == 'true' || needs.changed.outputs.workflow == 'true' }}
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Install Python"
uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "3.10" # Minimum of PYVERSIONS
cache: pip
cache-dependency-path: 'requirements/*.pip'
- name: "Install dependencies"
run: |
python -m pip install -r requirements/tox.pip
- name: "Tox mypy"
run: |
python -m tox -e mypy
doc:
name: "Build docs"
runs-on: ubuntu-latest
needs: changed
if: ${{ needs.changed.outputs.docs == 'true' || needs.changed.outputs.workflow == 'true' }}
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Fetch origin/master"
# rediraffe needs to compare to origin/master
run: |
git fetch origin master --depth=1
- name: "Install Python"
uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "3.11" # Doc version from PYVERSIONS
cache: pip
cache-dependency-path: 'requirements/*.pip'
- name: "Show environment"
run: |
set -xe
python -VV
python -m site
env | sort
- name: "Install dependencies"
run: |
set -xe
python -m pip install -r requirements/tox.pip
- name: "Tox doc"
run: |
python -m tox -e doc
zizmor:
name: "Zizmor GHA security check"
runs-on: ubuntu-latest
permissions:
contents: read
needs: changed
if: ${{ needs.changed.outputs.actions == 'true' || needs.changed.outputs.workflow == 'true' }}
steps:
- name: Checkout repository
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: Install the latest version of uv
uses: astral-sh/setup-uv@eb1897b8dc4b5d5bfe39a428a8f2304605e0983c #v7.0.0
with:
enable-cache: false
- name: Run zizmor
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: uvx zizmor --pedantic .github/workflows
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/workflows/testsuite.yml 0000644 0001751 0001751 00000012533 15073731535 021227 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
name: "Tests"
on:
push:
branches:
- master
- nedbat/*
pull_request:
workflow_dispatch:
defaults:
run:
shell: bash
env:
PIP_DISABLE_PIP_VERSION_CHECK: 1
COVERAGE_IGOR_VERBOSE: 1
FORCE_COLOR: 1 # Get colored pytest output
permissions:
contents: read
concurrency:
group: "${{ github.workflow }}-${{ github.ref }}"
cancel-in-progress: true
jobs:
changed:
name: "Check changed files"
runs-on: ubuntu-latest
permissions:
pull-requests: read # Needed for this check to run on pull requests
outputs:
run_tests: ${{ steps.filter.outputs.run_tests }}
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Examine changed files"
uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
id: filter
with:
filters: |
run_tests:
- "*.py"
- "coverage/**.py"
- "tests/**.py"
- "**.h"
- "**.c"
- ".github/workflows/testsuite.yml"
- "tox.ini"
- "requirements/*.pip"
- "tests/gold/**"
tests:
name: "${{ matrix.python-version }} on ${{ matrix.os }}"
runs-on: "${{ matrix.os }}-${{ matrix.os-version || 'latest' }}"
timeout-minutes: 30
# Don't run tests if the branch name includes "-notests".
# Only run tests if files that affect tests have changed.
needs: changed
if: ${{ needs.changed.outputs.run_tests == 'true' && !contains(github.ref, '-notests') }}
env:
TOX_GH_MAJOR_MINOR: "${{ matrix.python-version }}"
strategy:
matrix:
os:
- ubuntu
- macos
- windows
python-version:
# When changing this list, be sure to check the [gh] list in
# tox.ini so that tox will run properly. PYVERSIONS
# Available versions:
# https://github.com/actions/python-versions/blob/main/versions-manifest.json
# https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#available-versions-of-python-and-pypy
- "3.10"
- "3.11"
- "3.12"
- "3.13"
- "3.13t"
- "3.14"
- "3.14t"
- "3.15"
- "3.15t"
- "pypy-3.10"
- "pypy-3.11"
#
# If we need to exclude any combinations, do it like this:
# exclude:
# # Windows pypy 3.9 and 3.10 get stuck with PyPy 7.3.15.
# - os: windows
# python-version: "pypy-3.10"
#
# If we need to tweak the os version we can do it with an include like
# this:
# include:
# - python-version: "3.12"
# os: "macos"
# os-version: "15"
fail-fast: false
steps:
- name: "Check out the repo"
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false
- name: "Set up Python"
uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
with:
python-version: "${{ matrix.python-version }}"
allow-prereleases: true
# At a certain point, installing dependencies failed on pypy 3.9 and
# 3.10 on Windows. Commenting out the cache here fixed it. Someday
# try using the cache again.
#cache: pip
#cache-dependency-path: 'requirements/*.pip'
- name: "Show environment"
run: |
set -xe
python -VV
python -m site
# For extreme debugging:
# python -c "import urllib.request as r; exec(r.urlopen('https://bit.ly/pydoctor').read())"
env | sort
# Ideally, the system Python wouldn't have writable sitepackages so
# try to make it not writable. We can't always always change the
# permissions (Ubuntu & Windows yes, Mac no), so be ready for it to fail.
chmod u-w $(python -c "import site; print(site.getsitepackages()[0])") || echo "Couldn't lock down site-packages"
ls -ld $(python -c "import site; print(site.getsitepackages()[0])")
whoami
- name: "Install dependencies"
run: |
set -xe
python -m pip install -r requirements/tox.pip
- name: "Run tox for ${{ matrix.python-version }}"
run: |
python -m tox -- -rfsEX
- name: "Retry tox for ${{ matrix.python-version }}"
if: failure()
run: |
# `exit 1` makes sure that the job remains red with flaky runs
python -m tox -- -rfsEX --lf -vvvvv && exit 1
# This job aggregates test results. It's the required check for branch protection.
# https://github.com/marketplace/actions/alls-green#why
# https://github.com/orgs/community/discussions/33579
success:
name: Tests successful
needs:
- tests
runs-on: ubuntu-latest
steps:
- name: Decide whether the needed jobs succeeded or failed
uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
with:
jobs: ${{ toJSON(needs) }}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.github/zizmor.yml 0000644 0001751 0001751 00000000225 15073731535 016466 0 ustar 00runner runner # Rules for checking workflows
# https://woodruffw.github.io/zizmor
rules:
unpinned-uses:
config:
policies:
actions/*: hash-pin
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.ignore 0000644 0001751 0001751 00000000436 15073731535 014341 0 ustar 00runner runner # .ignore for coverage: controls what files get searched.
build/
htmlcov/
html0/
.tox*
.coverage*
.metacov
coverage.json
coverage.xml
coverage.lcov
*.min.js
style.css
tests/gold/*/*/*.*
sample_html/
sample_html_beta/
*.so
*.pyd
*.gz
*.zip
_build/
_spell/
*.egg
*.egg-info
.*_cache
tmp/
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.pre-commit-config.yaml 0000644 0001751 0001751 00000001605 15073731535 017335 0 ustar 00runner runner repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v6.0.0
hooks:
- id: check-case-conflict
- id: check-illegal-windows-names
- id: check-json
- id: check-merge-conflict
- id: check-symlinks
- id: check-toml
- id: check-xml
- id: check-yaml
- id: end-of-file-fixer
exclude: "(status\\.json|\\.min\\.js)$"
- id: trailing-whitespace
exclude: "stress_phystoken|\\.py,cover$"
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.14.0
hooks:
- id: ruff-format
- repo: https://github.com/pre-commit/pygrep-hooks
rev: v1.10.0
hooks:
- id: rst-directive-colons
- id: rst-inline-touching-normal
- repo: https://github.com/sphinx-contrib/sphinx-lint
rev: v1.0.0
hooks:
- id: sphinx-lint
- repo: meta
hooks:
- id: check-useless-excludes
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/.readthedocs.yaml 0000644 0001751 0001751 00000001122 15073731535 016275 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
#
# ReadTheDocs configuration.
# See https://docs.readthedocs.io/en/stable/config-file/v2.html
version: 2
build:
os: ubuntu-22.04
tools:
# PYVERSIONS: the version we use for building docs. Check tox.ini[doc] also.
python: "3.11"
sphinx:
builder: html
configuration: doc/conf.py
# Don't build anything except HTML.
formats: []
python:
install:
- requirements: doc/requirements.pip
- method: pip
path: .
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/CHANGES.rst 0000644 0001751 0001751 00000243235 15073731535 014665 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
==============================
Change history for coverage.py
==============================
These changes are listed in decreasing version number order. Note this can be
different from a strict chronological order when there are two branches in
development at the same time, such as 4.5.x and 5.0.
See :ref:`migrating` for significant changes that might be required when
upgrading your version of coverage.py.
.. When updating the "Unreleased" header to a specific version, use this
.. format. Don't forget the jump target:
..
.. .. _changes_9-8-1:
..
.. Version 9.8.1 โ 2027-07-27
.. --------------------------
.. start-releases
.. _changes_7-11-0:
Version 7.11.0 โ 2025-10-15
---------------------------
- Dropped support for Python 3.9, declared support for Python 3.15 alpha.
.. _changes_7-10-7:
Version 7.10.7 โ 2025-09-21
---------------------------
- Performance: with branch coverage in large files, generating HTML, JSON, or
LCOV reports could take far too long due to some quadratic behavior when
creating the function and class index pages. This is now fixed, closing
`issue 2048`_. Thanks to Daniel Diniz for help diagnosing the problem.
- Most warnings and a few errors now have links to a page in the docs
explaining the specific message. Closes `issue 1921`_.
.. _issue 1921: https://github.com/nedbat/coveragepy/issues/1921
.. _issue 2048: https://github.com/nedbat/coveragepy/issues/2048
.. _changes_7-10-6:
Version 7.10.6 โ 2025-08-29
---------------------------
- Fix: ``source`` directories were not properly communicated to subprocesses
that ran in different directories, as reported in `issue 1499`_. This is now
fixed.
- Performance: `Alex Gaynor continues fine-tuning `_ the speed of
combination, especially with many contexts.
.. _issue 1499: https://github.com/nedbat/coveragepy/issues/1499
.. _pull 2038: https://github.com/nedbat/coveragepy/pull/2038
.. _changes_7-10-5:
Version 7.10.5 โ 2025-08-23
---------------------------
- Big speed improvements for ``coverage combine``: it's now about twice as
fast! Huge thanks to Alex Gaynor for pull requests `2032 `_,
`2033 `_, and `2034 `_.
.. _pull 2032: https://github.com/nedbat/coveragepy/pull/2032
.. _pull 2033: https://github.com/nedbat/coveragepy/pull/2033
.. _pull 2034: https://github.com/nedbat/coveragepy/pull/2034
.. _changes_7-10-4:
Version 7.10.4 โ 2025-08-16
---------------------------
- Added ``patch = fork`` for times when the built-in forking support is
insufficient.
- Fix: ``patch = execv`` also inherits the entire coverage configuration now.
.. _changes_7-10-3:
Version 7.10.3 โ 2025-08-10
---------------------------
- Fixes for ``patch = subprocess``:
- If subprocesses spawned yet more subprocesses simultaneously, some coverage
could be missed. This is now fixed, closing `issue 2024`_.
- If subprocesses were created in other directories, their data files were
stranded there and not combined into the totals, as described in `issue
2025`_. This is now fixed.
- On Windows (or maybe only some Windows?) the patch would fail with a
``ModuleNotFound`` error trying to import coverage. This is now fixed,
closing `issue 2022`_.
- Originally only options set in the coverage configuration file would apply
to subprocesses. Options set on the ``coverage run`` command line (such as
``--branch``) wouldn't be communicated to the subprocesses. This could
lead to combining failures, as described in `issue 2021`_. Now the entire
configuration is used in subprocesses, regardless of its origin.
- Added ``debug=patch`` to help diagnose problems.
- Fix: really close all SQLite databases, even in-memory ones. Closes `issue
2017`_.
.. _issue 2017: https://github.com/nedbat/coveragepy/issues/2017
.. _issue 2021: https://github.com/nedbat/coveragepy/issues/2021
.. _issue 2022: https://github.com/nedbat/coveragepy/issues/2022
.. _issue 2024: https://github.com/nedbat/coveragepy/issues/2024
.. _issue 2025: https://github.com/nedbat/coveragepy/issues/2025
.. _changes_7-10-2:
Version 7.10.2 โ 2025-08-03
---------------------------
- Fix: some code with NOP bytecodes could report missing branches that are
actually executed. This is now fixed, closing `issue 1999`_. Python 3.9
still shows the problem.
.. _issue 1999: https://github.com/nedbat/coveragepy/issues/1999
.. _changes_7-10-1:
Version 7.10.1 โ 2025-07-27
---------------------------
- Fix: the exclusion for ``if TYPE_CHECKING:`` was wrong: it marked the branch
as partial, but it should have been a line exclusion so the entire clause
would be excluded. Improves `issue 831`_.
- Fix: changed where .pth files are written for ``patch = subprocess``, closing
`issue 2006`_.
.. _issue 2006: https://github.com/nedbat/coveragepy/issues/2006
.. _changes_7-10-0:
Version 7.10.0 โ 2025-07-24
---------------------------
- A new configuration option: ":ref:`config_run_patch`" specifies named patches
to work around some limitations in coverage measurement. These patches are
available:
- ``patch = _exit`` lets coverage save its data even when :func:`os._exit()
` is used to abruptly end the process. This closes
long-standing `issue 310`_ as well as its duplicates: `issue 312`_, `issue
1673`_, `issue 1845`_, and `issue 1941`_.
- ``patch = subprocess`` measures coverage in Python subprocesses created
with :mod:`subprocess`, :func:`os.system`, or one of the :func:`execv
` or :func:`spawnv ` family of
functions. Closes old `issue 367`_, its duplicate `issue 378`_ and old
`issue 689`_.
- ``patch = execv`` adjusts the :func:`execv ` family of
functions to save coverage data before ending the current program and
starting the next. Not available on Windows. Closes `issue 43`_ after 15
years!
- The HTML report now dimly colors subsequent lines in multi-line statements.
They used to have no color. This gives a better indication of the amount of
code missing in the report. Closes `issue 1308`_.
- Two new exclusion patterns are part of the defaults: ``...`` is automatically
excluded as a line and ``if TYPE_CHECKING:`` is excluded as a branch. Closes
`issue 831`_.
- A new command-line option: ``--save-signal=USR1`` specifies a signal that
coverage.py will listen for. When the signal is sent, the coverage data will
be saved. This makes it possible to save data from within long-running
processes. Thanks, `Arkady Gilinsky `_.
- A new configuration option: ":ref:`config_report_partial_also`" is a list of
regexes to add as pragmas for partial branches. This parallels the
":ref:`config_report_exclude_also`" setting for adding line exclusion
patterns.
- A few file path configuration settings didn't allow for tilde expansion:
:ref:`config_json_output`, :ref:`config_lcov_output` and
:ref:`config_run_debug_file`. This is now fixed.
- Wheels are included for 3.14 now that 3.14 rc1 is available.
- We no longer ship a PyPy-specific wheel. PyPy will install the pure-Python
wheel. Closes `issue 2001`_.
- In the very unusual situation of not having a current frame, coverage no
longer crashes when using the sysmon core, fixing `issue 2005`_.
.. _issue 43: https://github.com/nedbat/coveragepy/issues/43
.. _issue 310: https://github.com/nedbat/coveragepy/issues/310
.. _issue 312: https://github.com/nedbat/coveragepy/issues/312
.. _issue 367: https://github.com/nedbat/coveragepy/issues/367
.. _issue 378: https://github.com/nedbat/coveragepy/issues/378
.. _issue 689: https://github.com/nedbat/coveragepy/issues/689
.. _issue 831: https://github.com/nedbat/coveragepy/issues/831
.. _issue 1308: https://github.com/nedbat/coveragepy/issues/1308
.. _issue 1673: https://github.com/nedbat/coveragepy/issues/1673
.. _issue 1845: https://github.com/nedbat/coveragepy/issues/1845
.. _issue 1941: https://github.com/nedbat/coveragepy/issues/1941
.. _pull 1998: https://github.com/nedbat/coveragepy/pull/1998
.. _issue 2001: https://github.com/nedbat/coveragepy/issues/2001
.. _issue 2005: https://github.com/nedbat/coveragepy/issues/2005
.. _changes_7-9-2:
Version 7.9.2 โ 2025-07-03
--------------------------
- Fix: complex conditionals within a line might cause a KeyError when using
sys.monitoring, as reported in `issue 1991`_. This is now fixed.
- Fix: we can now measure coverage for code in Python archive (.par) files.
Thanks, `Itamer Oren `_.
.. _pull 1984: https://github.com/nedbat/coveragepy/pull/1984
.. _issue 1991: https://github.com/nedbat/coveragepy/issues/1991
.. _changes_7-9-1:
Version 7.9.1 โ 2025-06-13
--------------------------
- The "no-ctracer" warning is not issued for Python pre-release versions.
Coverage doesn't ship compiled wheels for those versions, so this was far too
noisy.
- On Python 3.14+, the "sysmon" core is now the default if it's supported for
your configuration. Plugins and dynamic contexts are still not supported
with it.
.. _changes_7-9-0:
Version 7.9.0 โ 2025-06-11
--------------------------
- Added a ``[run] core`` configuration setting to specify the measurement core,
which was previously only available through the COVERAGE_CORE environment
variable. Finishes `issue 1746`_.
- Fixed incorrect rendering of f-strings with doubled braces, closing `issue
1980`_.
- If the C tracer core can't be imported, a warning ("no-ctracer") is issued
with the reason.
- The C tracer core extension module now conforms to `PEP 489`_, closing `issue
1977`_. Thanks, `Adam Turner `_.
- Fixed a "ValueError: min() arg is an empty sequence" error caused by strange
empty modules, found by `oss-fuzz`_.
.. _issue 1746: https://github.com/nedbat/coveragepy/issues/1746
.. _issue 1977: https://github.com/nedbat/coveragepy/issues/1977
.. _pull 1978: https://github.com/nedbat/coveragepy/pull/1978
.. _issue 1980: https://github.com/nedbat/coveragepy/issues/1980
.. _PEP 489: https://peps.python.org/pep-0489
.. _oss-fuzz: https://google.github.io/oss-fuzz/
.. _changes_7-8-2:
Version 7.8.2 โ 2025-05-23
--------------------------
- Wheels are provided for Windows ARM64 on Python 3.11, 3.12, and 3.13.
Thanks, `Finn Womack `_.
.. _issue 1971: https://github.com/nedbat/coveragepy/pull/1971
.. _pull 1972: https://github.com/nedbat/coveragepy/pull/1972
.. _changes_7-8-1:
Version 7.8.1 โ 2025-05-21
--------------------------
- A number of EncodingWarnings were fixed that could appear if you've enabled
PYTHONWARNDEFAULTENCODING, fixing `issue 1966`_. Thanks, `Henry Schreiner
`_.
- Fixed a race condition when using sys.monitoring with free-threading Python,
closing `issue 1970`_.
.. _issue 1966: https://github.com/nedbat/coveragepy/issues/1966
.. _pull 1967: https://github.com/nedbat/coveragepy/pull/1967
.. _issue 1970: https://github.com/nedbat/coveragepy/issues/1970
.. _changes_7-8-0:
Version 7.8.0 โ 2025-03-30
--------------------------
- Added a new ``source_dirs`` setting for symmetry with the existing
``source_pkgs`` setting. It's preferable to the existing ``source`` setting,
because you'll get a clear error when directories don't exist. Fixes `issue
1942`_. Thanks, `Jeremy Fleischman `_.
- Fix: the PYTHONSAFEPATH environment variable new in Python 3.11 is properly
supported, closing `issue 1696`_. Thanks, `Philipp A. `_. This
works properly except for a detail when using the ``coverage`` command on
Windows. There you can use ``python -m coverage`` instead if you need exact
emulation.
.. _issue 1696: https://github.com/nedbat/coveragepy/issues/1696
.. _pull 1700: https://github.com/nedbat/coveragepy/pull/1700
.. _issue 1942: https://github.com/nedbat/coveragepy/issues/1942
.. _pull 1943: https://github.com/nedbat/coveragepy/pull/1943
.. _changes_7-7-1:
Version 7.7.1 โ 2025-03-21
--------------------------
- A few small tweaks to the sys.monitoring support for Python 3.14. Please
test!
.. _changes_7-7-0:
Version 7.7.0 โ 2025-03-16
--------------------------
- The Coverage object has a new method, :meth:`.Coverage.branch_stats` for
getting simple branch information for a module. Closes `issue 1888`_.
- The :class:`Coverage constructor<.Coverage>` now has a ``plugins`` parameter
for passing in plugin objects directly, thanks to `Alex Gaynor `_.
- Many constant tests in if statements are now recognized as being optimized
away. For example, previously ``if 13:`` would have been considered a branch
with one path not taken. Now it is understood as always true and no coverage
is missing.
- The experimental sys.monitoring support now works for branch coverage if you
are using Python 3.14.0 alpha 6 or newer. This should reduce the overhead
coverage.py imposes on your test suite. Set the environment variable
``COVERAGE_CORE=sysmon`` to try it out.
- Confirmed support for PyPy 3.11. Thanks Michaล Gรณrny.
.. _issue 1888: https://github.com/nedbat/coveragepy/issues/1888
.. _pull 1919: https://github.com/nedbat/coveragepy/pull/1919
.. _changes_7-6-12:
Version 7.6.12 โ 2025-02-11
---------------------------
- Fix: some aarch64 distributions were missing (`issue 1927`_). These are now
building reliably.
.. _issue 1927: https://github.com/nedbat/coveragepy/issues/1927
.. _changes_7-6-11:
Version 7.6.11 โ 2025-02-08
---------------------------
- Fix: a memory leak in CTracer has been fixed. The details are in `issue
1924`_ and `pytest-dev 676`_. This should reduce the memory footprint for
everyone even if it hadn't caused a problem before.
- We now ship a py3-none-any.whl wheel file. Thanks, `Russell Keith-Magee
`_.
.. _pull 1914: https://github.com/nedbat/coveragepy/pull/1914
.. _issue 1924: https://github.com/nedbat/coveragepy/issues/1924
.. _pytest-dev 676: https://github.com/pytest-dev/pytest-cov/issues/676
.. _changes_7-6-10:
Version 7.6.10 โ 2024-12-26
---------------------------
- Fix: some descriptions of missing branches in HTML and LCOV reports were
incorrect when multi-line statements were involved (`issue 1874`_ and `issue
1875`_). These are now fixed.
- Fix: Python 3.14 `defers evaluation of annotations `_ by moving them
into separate code objects. That code is rarely executed, so coverage.py
would mark them as missing, as reported in `issue 1908`_. Now they are
ignored by coverage automatically.
- Fixed an obscure and mysterious problem on PyPy 3.10 seemingly involving
mocks, imports, and trace functions: `issue 1902`_. To be honest, I don't
understand the problem or the solution, but ``git bisect`` helped find it,
and now it's fixed.
- Docs: re-wrote the :ref:`subprocess` page to put multiprocessing first and to
highlight the correct use of :class:`multiprocessing.Pool
`.
.. _issue 1874: https://github.com/nedbat/coveragepy/issues/1874
.. _issue 1875: https://github.com/nedbat/coveragepy/issues/1875
.. _issue 1902: https://github.com/nedbat/coveragepy/issues/1902
.. _issue 1908: https://github.com/nedbat/coveragepy/issues/1908
.. _pep649: https://docs.python.org/3.14/whatsnew/3.14.html#whatsnew314-deferred-annotations
.. _changes_7-6-9:
Version 7.6.9 โ 2024-12-06
--------------------------
- Fix: `Tomas Uribe fixed `_ a performance problem in the XML
report. Large code bases should produce XML reports much faster now.
.. _pull 1901: https://github.com/nedbat/coveragepy/pull/1901
.. _changes_7-6-8:
Version 7.6.8 โ 2024-11-23
--------------------------
- Fix: the LCOV report code assumed that a branch line that took no branches
meant that the entire line was unexecuted. This isn't true in a few cases:
the line might always raise an exception, or might have been optimized away.
Fixes `issue 1896`_.
- Fix: similarly, the HTML report will now explain that a line that jumps to
none of its expected destinations must have always raised an exception.
Previously, it would say something nonsensical like, "line 4 didn't jump to
line 5 because line 4 was never true, and it didn't jump to line 7 because
line 4 was always true." This was also shown in `issue 1896`_.
.. _issue 1896: https://github.com/nedbat/coveragepy/issues/1896
.. _changes_7-6-7:
Version 7.6.7 โ 2024-11-15
--------------------------
- Fix: ugh, the other assert from 7.6.5 can also be encountered in the wild,
so it's been restored to a conditional. Sorry for the churn.
.. _changes_7-6-6:
Version 7.6.6 โ 2024-11-15
--------------------------
- One of the new asserts from 7.6.5 caused problems in real projects, as
reported in `issue 1891`_. The assert has been removed.
.. _issue 1891: https://github.com/nedbat/coveragepy/issues/1891
.. _changes_7-6-5:
Version 7.6.5 โ 2024-11-14
--------------------------
- Fix: fine-tuned the exact Python version (3.12.6) when exiting from ``with``
statements changed how they traced. This affected whether people saw the
fix for `issue 1880`_.
- Fix: isolate our code more from mocking in the os module that in rare cases
can cause `bizarre behavior `_.
- Refactor: some code unreachable code paths in parser.py were changed to
asserts. If you encounter any of these, please let me know!
.. _pytest-cov-666: https://github.com/pytest-dev/pytest-cov/issues/666
.. _changes_7-6-4:
Version 7.6.4 โ 2024-10-20
--------------------------
- Fix: multi-line ``with`` statements could cause contained branches to be
incorrectly marked as missing (`issue 1880`_). This is now fixed.
.. _issue 1880: https://github.com/nedbat/coveragepy/issues/1880
.. _changes_7-6-3:
Version 7.6.3 โ 2024-10-13
--------------------------
- Fix: nested context managers could incorrectly be analyzed to flag a missing
branch on the last context manager, as described in `issue 1876`_. This is
now fixed.
- Fix: the missing branch message about not exiting a module had an extra
"didn't," as described in `issue 1873`_. This is now fixed.
.. _issue 1873: https://github.com/nedbat/coveragepy/issues/1873
.. _issue 1876: https://github.com/nedbat/coveragepy/issues/1876
.. _changes_7-6-2:
Version 7.6.2 โ 2024-10-09
--------------------------
- Dropped support for Python 3.8 and PyPy 3.8.
- Fix: a final wildcard match/case clause assigning to a name (``case _ as
value``) was incorrectly marked as a missing branch. This is now fixed,
closing `issue 1860`_.
- Fewer things are considered branches now. Lambdas, comprehensions, and
generator expressions are no longer marked as missing branches if they don't
complete execution. Closes `issue 1852`_.
- Fix: the HTML report didn't properly show multi-line f-strings that end with
a backslash continuation. This is now fixed, closing `issue 1836`_, thanks
to `LiuYinCarl and Marco Ricci `_.
- Fix: the LCOV report now has correct line numbers (fixing `issue 1846`_) and
better branch descriptions for BRDA records (fixing `issue 1850`_). There
are other changes to lcov also, including a new configuration option
:ref:`line_checksums ` to control whether line
checksums are included in the lcov report. The default is false. To keep
checksums set it to true. All this work is thanks to Zack Weinberg
(`pull 1849`_ and `pull 1851`_).
- Fixed the docs for multi-line regex exclusions, closing `issue 1863`_.
- Fixed a potential crash in the C tracer, closing `issue 1835`_, thanks to
`Jan Kรผhle `_.
.. _issue 1835: https://github.com/nedbat/coveragepy/issues/1835
.. _issue 1836: https://github.com/nedbat/coveragepy/issues/1836
.. _pull 1838: https://github.com/nedbat/coveragepy/pull/1838
.. _pull 1843: https://github.com/nedbat/coveragepy/pull/1843
.. _issue 1846: https://github.com/nedbat/coveragepy/issues/1846
.. _pull 1849: https://github.com/nedbat/coveragepy/pull/1849
.. _issue 1850: https://github.com/nedbat/coveragepy/issues/1850
.. _pull 1851: https://github.com/nedbat/coveragepy/pull/1851
.. _issue 1852: https://github.com/nedbat/coveragepy/issues/1852
.. _issue 1860: https://github.com/nedbat/coveragepy/issues/1860
.. _issue 1863: https://github.com/nedbat/coveragepy/issues/1863
.. _changes_7-6-1:
Version 7.6.1 โ 2024-08-04
--------------------------
- Fix: coverage used to fail when measuring code using :func:`runpy.run_path
` with a :class:`Path ` argument.
This is now fixed, thanks to `Ask Hjorth Larsen `_.
- Fix: backslashes preceding a multi-line backslashed string could confuse the
HTML report. This is now fixed, thanks to `LiuYinCarl `_.
- Now we publish wheels for Python 3.13, both regular and free-threaded.
.. _pull 1819: https://github.com/nedbat/coveragepy/pull/1819
.. _pull 1828: https://github.com/nedbat/coveragepy/pull/1828
.. _changes_7-6-0:
Version 7.6.0 โ 2024-07-11
--------------------------
- Exclusion patterns can now be multi-line, thanks to `Daniel Diniz `_. This enables many interesting exclusion use-cases, including those
requested in issues `118 `_ (entire files), `996
`_ (multiple lines only when appearing together), `1741
`_ (remainder of a function), and `1803 `_
(arbitrary sequence of marked lines). See the :ref:`multi_line_exclude`
section of the docs for more details and examples.
- The JSON report now includes per-function and per-class coverage information.
Thanks to `Daniel Diniz `_ for getting the work started. This
closes `issue 1793`_ and `issue 1532`_.
- Fixed an incorrect calculation of "(no class)" lines in the HTML classes
report.
- Python 3.13.0b3 is supported.
.. _issue 118: https://github.com/nedbat/coveragepy/issues/118
.. _issue 996: https://github.com/nedbat/coveragepy/issues/996
.. _issue 1532: https://github.com/nedbat/coveragepy/issues/1532
.. _issue 1741: https://github.com/nedbat/coveragepy/issues/1741
.. _issue 1793: https://github.com/nedbat/coveragepy/issues/1793
.. _issue 1803: https://github.com/nedbat/coveragepy/issues/1803
.. _pull 1807: https://github.com/nedbat/coveragepy/pull/1807
.. _pull 1809: https://github.com/nedbat/coveragepy/pull/1809
.. _changes_7-5-4:
Version 7.5.4 โ 2024-06-22
--------------------------
- If you attempt to combine statement coverage data with branch coverage data,
coverage.py used to fail with the message "Can't combine arc data with line
data" or its reverse, "Can't combine line data with arc data." These
messages used internal terminology, making it hard for people to understand
the problem. They are now changed to mention "branch coverage data" and
"statement coverage data."
- Fixed a minor branch coverage problem with wildcard match/case cases using
names or guard clauses.
- Started testing on 3.13 free-threading (nogil) builds of Python. I'm not
claiming full support yet. Closes `issue 1799`_.
.. _issue 1799: https://github.com/nedbat/coveragepy/issues/1799
.. _changes_7-5-3:
Version 7.5.3 โ 2024-05-28
--------------------------
- Performance improvements for combining data files, especially when measuring
line coverage. A few different quadratic behaviors were eliminated. In one
extreme case of combining 700+ data files, the time dropped from more than
three hours to seven minutes. Thanks for Kraken Tech for funding the fix.
- Performance improvements for generating HTML reports, with a side benefit of
reducing memory use, closing `issue 1791`_. Thanks to Daniel Diniz for
helping to diagnose the problem.
.. _issue 1791: https://github.com/nedbat/coveragepy/issues/1791
.. _changes_7-5-2:
Version 7.5.2 โ 2024-05-24
--------------------------
- Fix: nested matches of exclude patterns could exclude too much code, as
reported in `issue 1779`_. This is now fixed.
- Changed: previously, coverage.py would consider a module docstring to be an
executable statement if it appeared after line 1 in the file, but not
executable if it was the first line. Now module docstrings are never counted
as executable statements. This can change coverage.py's count of the number
of statements in a file, which can slightly change the coverage percentage
reported.
- In the HTML report, the filter term and "hide covered" checkbox settings are
remembered between viewings, thanks to `Daniel Diniz `_.
- Python 3.13.0b1 is supported.
- Fix: parsing error handling is improved to ensure bizarre source files are
handled gracefully, and to unblock oss-fuzz fuzzing, thanks to `Liam DeVoe
`_. Closes `issue 1787`_.
.. _pull 1776: https://github.com/nedbat/coveragepy/pull/1776
.. _issue 1779: https://github.com/nedbat/coveragepy/issues/1779
.. _issue 1787: https://github.com/nedbat/coveragepy/issues/1787
.. _pull 1788: https://github.com/nedbat/coveragepy/pull/1788
.. _changes_7-5-1:
Version 7.5.1 โ 2024-05-04
--------------------------
- Fix: a pragma comment on the continuation lines of a multi-line statement
now excludes the statement and its body, the same as if the pragma is
on the first line. This closes `issue 754`_. The fix was contributed by
`Daniel Diniz `_.
- Fix: very complex source files like `this one `_ could
cause a maximum recursion error when creating an HTML report. This is now
fixed, closing `issue 1774`_.
- HTML report improvements:
- Support files (JavaScript and CSS) referenced by the HTML report now have
hashes added to their names to ensure updated files are used instead of
stale cached copies.
- Missing branch coverage explanations that said "the condition was never
false" now read "the condition was always true" because it's easier to
understand.
- Column sort order is remembered better as you move between the index pages,
fixing `issue 1766`_. Thanks, `Daniel Diniz `_.
.. _resolvent_lookup: https://github.com/sympy/sympy/blob/130950f3e6b3f97fcc17f4599ac08f70fdd2e9d4/sympy/polys/numberfields/resolvent_lookup.py
.. _issue 754: https://github.com/nedbat/coveragepy/issues/754
.. _issue 1766: https://github.com/nedbat/coveragepy/issues/1766
.. _pull 1768: https://github.com/nedbat/coveragepy/pull/1768
.. _pull 1773: https://github.com/nedbat/coveragepy/pull/1773
.. _issue 1774: https://github.com/nedbat/coveragepy/issues/1774
.. _changes_7-5-0:
Version 7.5.0 โ 2024-04-23
--------------------------
- Added initial support for function and class reporting in the HTML report.
There are now three index pages which link to each other: files, functions,
and classes. Other reports don't yet have this information, but it will be
added in the future where it makes sense. Feedback gladly accepted!
Finishes `issue 780`_.
- Other HTML report improvements:
- There is now a "hide covered" checkbox to filter out 100% files, finishing
`issue 1384`_.
- The index page is always sorted by one of its columns, with clearer
indications of the sorting.
- The "previous file" shortcut key didn't work on the index page, but now it
does, fixing `issue 1765`_.
- The debug output showing which configuration files were tried now shows
absolute paths to help diagnose problems where settings aren't taking effect,
and is renamed from "attempted_config_files" to the more logical
"config_files_attempted."
- Python 3.13.0a6 is supported.
.. _issue 780: https://github.com/nedbat/coveragepy/issues/780
.. _issue 1384: https://github.com/nedbat/coveragepy/issues/1384
.. _issue 1765: https://github.com/nedbat/coveragepy/issues/1765
.. _changes_7-4-4:
Version 7.4.4 โ 2024-03-14
--------------------------
- Fix: in some cases, even with ``[run] relative_files=True``, a data file
could be created with absolute path names. When combined with other relative
data files, it was random whether the absolute file names would be made
relative or not. If they weren't, then a file would be listed twice in
reports, as detailed in `issue 1752`_. This is now fixed: absolute file
names are always made relative when combining. Thanks to Bruno Rodrigues dos
Santos for support.
- Fix: the last case of a match/case statement had an incorrect message if the
branch was missed. It said the pattern never matched, when actually the
branch is missed if the last case always matched.
- Fix: clicking a line number in the HTML report now positions more accurately.
- Fix: the ``report:format`` setting was defined as a boolean, but should be a
string. Thanks, `Tanaydin Sirin `_. It is also now documented
on the :ref:`configuration page `.
.. _issue 1752: https://github.com/nedbat/coveragepy/issues/1752
.. _pull 1754: https://github.com/nedbat/coveragepy/pull/1754
.. _changes_7-4-3:
Version 7.4.3 โ 2024-02-23
--------------------------
- Fix: in some cases, coverage could fail with a RuntimeError: "Set changed
size during iteration." This is now fixed, closing `issue 1733`_.
.. _issue 1733: https://github.com/nedbat/coveragepy/issues/1733
.. _changes_7-4-2:
Version 7.4.2 โ 2024-02-20
--------------------------
- Fix: setting ``COVERAGE_CORE=sysmon`` no longer errors on 3.11 and lower,
thanks `Hugo van Kemenade `_. It now issues a warning that
sys.monitoring is not available and falls back to the default core instead.
.. _pull 1747: https://github.com/nedbat/coveragepy/pull/1747
.. _changes_7-4-1:
Version 7.4.1 โ 2024-01-26
--------------------------
- Python 3.13.0a3 is supported.
- Fix: the JSON report now includes an explicit format version number, closing
`issue 1732`_.
.. _issue 1732: https://github.com/nedbat/coveragepy/issues/1732
.. _changes_7-4-0:
Version 7.4.0 โ 2023-12-27
--------------------------
- In Python 3.12 and above, you can try an experimental core based on the new
:mod:`sys.monitoring ` module by defining a
``COVERAGE_CORE=sysmon`` environment variable. This should be faster for
line coverage, but not for branch coverage, and plugins and dynamic contexts
are not yet supported with it. I am very interested to hear how it works (or
doesn't!) for you.
.. _changes_7-3-4:
Version 7.3.4 โ 2023-12-20
--------------------------
- Fix: the change for multi-line signature exclusions in 7.3.3 broke other
forms of nested clauses being excluded properly. This is now fixed, closing
`issue 1713`_.
- Fix: in the HTML report, selecting code for copying won't select the line
numbers also. Thanks, `Robert Harris `_.
.. _issue 1713: https://github.com/nedbat/coveragepy/issues/1713
.. _pull 1717: https://github.com/nedbat/coveragepy/pull/1717
.. _changes_7-3-3:
Version 7.3.3 โ 2023-12-14
--------------------------
- Fix: function definitions with multi-line signatures can now be excluded by
matching any of the lines, closing `issue 684`_. Thanks, `Jan Rusak,
Maciej Kowalczyk and Joanna Ejzel `_.
- Fix: XML reports could fail with a TypeError if files had numeric components
that were duplicates except for leading zeroes, like ``file1.py`` and
``file001.py``. Fixes `issue 1709`_.
- The ``coverage annotate`` command used to announce that it would be removed
in a future version. Enough people got in touch to say that they use it, so
it will stay. Don't expect it to keep up with other new features though.
- Added new :ref:`debug options `:
- ``pytest`` writes the pytest test name into the debug output.
- ``dataop2`` writes the full data being added to CoverageData objects.
.. _issue 684: https://github.com/nedbat/coveragepy/issues/684
.. _pull 1705: https://github.com/nedbat/coveragepy/pull/1705
.. _issue 1709: https://github.com/nedbat/coveragepy/issues/1709
.. _changes_7-3-2:
Version 7.3.2 โ 2023-10-02
--------------------------
- The ``coverage lcov`` command ignored the ``[report] exclude_lines`` and
``[report] exclude_also`` settings (`issue 1684`_). This is now fixed,
thanks `Jacqueline Lee `_.
- Sometimes SQLite will create journal files alongside the coverage.py database
files. These are ephemeral, but could be mistakenly included when combining
data files. Now they are always ignored, fixing `issue 1605`_. Thanks to
Brad Smith for suggesting fixes and providing detailed debugging.
- On Python 3.12+, we now disable SQLite writing journal files, which should be
a little faster.
- The new 3.12 soft keyword ``type`` is properly bolded in HTML reports.
- Removed the "fullcoverage" feature used by CPython to measure the coverage of
early-imported standard library modules. CPython `stopped using it
<88054_>`_ in 2021, and it stopped working completely in Python 3.13.
.. _issue 1605: https://github.com/nedbat/coveragepy/issues/1605
.. _issue 1684: https://github.com/nedbat/coveragepy/issues/1684
.. _pull 1685: https://github.com/nedbat/coveragepy/pull/1685
.. _88054: https://github.com/python/cpython/issues/88054
.. _changes_7-3-1:
Version 7.3.1 โ 2023-09-06
--------------------------
- The semantics of stars in file patterns has been clarified in the docs. A
leading or trailing star matches any number of path components, like a double
star would. This is different than the behavior of a star in the middle of a
pattern. This discrepancy was `identified by Sviatoslav Sydorenko
`_, who `provided patient detailed diagnosis `_ and
graciously agreed to a pragmatic resolution.
- The API docs were missing from the last version. They are now `restored
`_.
.. _apidocs: https://coverage.readthedocs.io/en/latest/api_coverage.html
.. _starbad: https://github.com/nedbat/coveragepy/issues/1407#issuecomment-1631085209
.. _pull 1650: https://github.com/nedbat/coveragepy/pull/1650
.. _changes_7-3-0:
Version 7.3.0 โ 2023-08-12
--------------------------
- Added a :meth:`.Coverage.collect` context manager to start and stop coverage
data collection.
- Dropped support for Python 3.7.
- Fix: in unusual circumstances, SQLite cannot be set to asynchronous mode.
Coverage.py would fail with the error ``Safety level may not be changed
inside a transaction.`` This is now avoided, closing `issue 1646`_. Thanks
to Michael Bell for the detailed bug report.
- Docs: examples of configuration files now include separate examples for the
different syntaxes: .coveragerc, pyproject.toml, setup.cfg, and tox.ini.
- Fix: added ``nosemgrep`` comments to our JavaScript code so that
semgrep-based SAST security checks won't raise false alarms about security
problems that aren't problems.
- Added a CITATION.cff file, thanks to `Ken Schackart `_.
.. _pull 1641: https://github.com/nedbat/coveragepy/pull/1641
.. _issue 1646: https://github.com/nedbat/coveragepy/issues/1646
.. _changes_7-2-7:
Version 7.2.7 โ 2023-05-29
--------------------------
- Fix: reverted a `change from 6.4.3 `_ that helped Cython, but
also increased the size of data files when using dynamic contexts, as
described in the now-fixed `issue 1586`_. The problem is now avoided due to a
recent change (`issue 1538 `_). Thanks to `Anders Kaseorg
`_ and David Szotten for persisting with problem reports and
detailed diagnoses.
- Wheels are now provided for CPython 3.12.
.. _pull 1347b: https://github.com/nedbat/coveragepy/pull/1347
.. _issue 1538b: https://github.com/nedbat/coveragepy/issues/1538
.. _issue 1586: https://github.com/nedbat/coveragepy/issues/1586
.. _pull 1629: https://github.com/nedbat/coveragepy/pull/1629
.. _changes_7-2-6:
Version 7.2.6 โ 2023-05-23
--------------------------
- Fix: the ``lcov`` command could raise an IndexError exception if a file is
translated to Python but then executed under its own name. Jinja2 does this
when rendering templates. Fixes `issue 1553`_.
- Python 3.12 beta 1 now inlines comprehensions. Previously they were compiled
as invisible functions and coverage.py would warn you if they weren't
completely executed. This no longer happens under Python 3.12.
- Fix: the ``coverage debug sys`` command includes some environment variables
in its output. This could have included sensitive data. Those values are
now hidden with asterisks, closing `issue 1628`_.
.. _issue 1553: https://github.com/nedbat/coveragepy/issues/1553
.. _issue 1628: https://github.com/nedbat/coveragepy/issues/1628
.. _changes_7-2-5:
Version 7.2.5 โ 2023-04-30
--------------------------
- Fix: ``html_report()`` could fail with an AttributeError on ``isatty`` if run
in an unusual environment where sys.stdout had been replaced. This is now
fixed.
.. _changes_7-2-4:
Version 7.2.4 โ 2023-04-28
--------------------------
PyCon 2023 sprint fixes!
- Fix: with ``relative_files = true``, specifying a specific file to include or
omit wouldn't work correctly (`issue 1604`_). This is now fixed, with
testing help by `Marc Gibbons `_.
- Fix: the XML report would have an incorrect ```` element when using
relative files and the source option ended with a slash (`issue 1541`_).
This is now fixed, thanks to `Kevin Brown-Silva `_.
- When the HTML report location is printed to the terminal, it's now a
terminal-compatible URL, so that you can click the location to open the HTML
file in your browser. Finishes `issue 1523`_ thanks to `Ricardo Newbery
`_.
- Docs: a new :ref:`Migrating page ` with details about how to
migrate between major versions of coverage.py. It currently covers the
wildcard changes in 7.x. Thanks, `Brian Grohe `_.
.. _issue 1523: https://github.com/nedbat/coveragepy/issues/1523
.. _issue 1541: https://github.com/nedbat/coveragepy/issues/1541
.. _issue 1604: https://github.com/nedbat/coveragepy/issues/1604
.. _pull 1608: https://github.com/nedbat/coveragepy/pull/1608
.. _pull 1609: https://github.com/nedbat/coveragepy/pull/1609
.. _pull 1610: https://github.com/nedbat/coveragepy/pull/1610
.. _pull 1613: https://github.com/nedbat/coveragepy/pull/1613
.. _changes_7-2-3:
Version 7.2.3 โ 2023-04-06
--------------------------
- Fix: the :ref:`config_run_sigterm` setting was meant to capture data if a
process was terminated with a SIGTERM signal, but it didn't always. This was
fixed thanks to `Lewis Gaul `_, closing `issue 1599`_.
- Performance: HTML reports with context information are now much more compact.
File sizes are typically as small as one-third the previous size, but can be
dramatically smaller. This closes `issue 1584`_ thanks to `Oleh Krehel
`_.
- Development dependencies no longer use hashed pins, closing `issue 1592`_.
.. _issue 1584: https://github.com/nedbat/coveragepy/issues/1584
.. _pull 1587: https://github.com/nedbat/coveragepy/pull/1587
.. _issue 1592: https://github.com/nedbat/coveragepy/issues/1592
.. _issue 1599: https://github.com/nedbat/coveragepy/issues/1599
.. _pull 1600: https://github.com/nedbat/coveragepy/pull/1600
.. _changes_7-2-2:
Version 7.2.2 โ 2023-03-16
--------------------------
- Fix: if a virtualenv was created inside a source directory, and a sourced
package was installed inside the virtualenv, then all of the third-party
packages inside the virtualenv would be measured. This was incorrect, but
has now been fixed: only the specified packages will be measured, thanks to
`Manuel Jacob `_.
- Fix: the ``coverage lcov`` command could create a .lcov file with incorrect
LF (lines found) and LH (lines hit) totals. This is now fixed, thanks to
`Ian Moore `_.
- Fix: the ``coverage xml`` command on Windows could create a .xml file with
duplicate ```` elements. This is now fixed, thanks to `Benjamin
Parzella `_, closing `issue 1573`_.
.. _pull 1560: https://github.com/nedbat/coveragepy/pull/1560
.. _issue 1573: https://github.com/nedbat/coveragepy/issues/1573
.. _pull 1574: https://github.com/nedbat/coveragepy/pull/1574
.. _pull 1583: https://github.com/nedbat/coveragepy/pull/1583
.. _changes_7-2-1:
Version 7.2.1 โ 2023-02-26
--------------------------
- Fix: the PyPI page had broken links to documentation pages, but no longer
does, closing `issue 1566`_.
- Fix: public members of the coverage module are now properly indicated so that
mypy will find them, fixing `issue 1564`_.
.. _issue 1564: https://github.com/nedbat/coveragepy/issues/1564
.. _issue 1566: https://github.com/nedbat/coveragepy/issues/1566
.. _changes_7-2-0:
Version 7.2.0 โ 2023-02-22
--------------------------
- Added a new setting ``[report] exclude_also`` to let you add more exclusions
without overwriting the defaults. Thanks, `Alpha Chen `_,
closing `issue 1391`_.
- Added a :meth:`.CoverageData.purge_files` method to remove recorded data for
a particular file. Contributed by `Stephan Deibel `_.
- Fix: when reporting commands fail, they will no longer congratulate
themselves with messages like "Wrote XML report to file.xml" before spewing a
traceback about their failure.
- Fix: arguments in the public API that name file paths now accept pathlib.Path
objects. This includes the ``data_file`` and ``config_file`` arguments to
the Coverage constructor and the ``basename`` argument to CoverageData.
Closes `issue 1552`_.
- Fix: In some embedded environments, an IndexError could occur on stop() when
the originating thread exits before completion. This is now fixed, thanks to
`Russell Keith-Magee `_, closing `issue 1542`_.
- Added a ``py.typed`` file to announce our type-hintedness. Thanks,
`KotlinIsland `_.
.. _issue 1391: https://github.com/nedbat/coveragepy/issues/1391
.. _issue 1542: https://github.com/nedbat/coveragepy/issues/1542
.. _pull 1543: https://github.com/nedbat/coveragepy/pull/1543
.. _pull 1547: https://github.com/nedbat/coveragepy/pull/1547
.. _pull 1550: https://github.com/nedbat/coveragepy/pull/1550
.. _issue 1552: https://github.com/nedbat/coveragepy/issues/1552
.. _pull 1557: https://github.com/nedbat/coveragepy/pull/1557
.. _changes_7-1-0:
Version 7.1.0 โ 2023-01-24
--------------------------
- Added: the debug output file can now be specified with ``[run] debug_file``
in the configuration file. Closes `issue 1319`_.
- Performance: fixed a slowdown with dynamic contexts that's been around since
6.4.3. The fix closes `issue 1538`_. Thankfully this doesn't break the
`Cython change`_ that fixed `issue 972`_. Thanks to Mathieu Kniewallner for
the deep investigative work and comprehensive issue report.
- Typing: all product and test code has type annotations.
.. _Cython change: https://github.com/nedbat/coveragepy/pull/1347
.. _issue 972: https://github.com/nedbat/coveragepy/issues/972
.. _issue 1319: https://github.com/nedbat/coveragepy/issues/1319
.. _issue 1538: https://github.com/nedbat/coveragepy/issues/1538
.. _changes_7-0-5:
Version 7.0.5 โ 2023-01-10
--------------------------
- Fix: On Python 3.7, a file with type annotations but no ``from __future__
import annotations`` would be missing statements in the coverage report. This
is now fixed, closing `issue 1524`_.
.. _issue 1524: https://github.com/nedbat/coveragepy/issues/1524
.. _changes_7-0-4:
Version 7.0.4 โ 2023-01-07
--------------------------
- Performance: an internal cache of file names was accidentally disabled,
resulting in sometimes drastic reductions in performance. This is now fixed,
closing `issue 1527`_. Thanks to Ivan Ciuvalschii for the reproducible test
case.
.. _issue 1527: https://github.com/nedbat/coveragepy/issues/1527
.. _changes_7-0-3:
Version 7.0.3 โ 2023-01-03
--------------------------
- Fix: when using pytest-cov or pytest-xdist, or perhaps both, the combining
step could fail with ``assert row is not None`` using 7.0.2. This was due to
a race condition that has always been possible and is still possible. In
7.0.1 and before, the error was silently swallowed by the combining code.
Now it will produce a message "Couldn't combine data file" and ignore the
data file as it used to do before 7.0.2. Closes `issue 1522`_.
.. _issue 1522: https://github.com/nedbat/coveragepy/issues/1522
.. _changes_7-0-2:
Version 7.0.2 โ 2023-01-02
--------------------------
- Fix: when using the ``[run] relative_files = True`` setting, a relative
``[paths]`` pattern was still being made absolute. This is now fixed,
closing `issue 1519`_.
- Fix: if Python doesn't provide tomllib, then TOML configuration files can
only be read if coverage.py is installed with the ``[toml]`` extra.
Coverage.py will raise an error if TOML support is not installed when it sees
your settings are in a .toml file. But it didn't understand that
``[tools.coverage]`` was a valid section header, so the error wasn't reported
if you used that header, and settings were silently ignored. This is now
fixed, closing `issue 1516`_.
- Fix: adjusted how decorators are traced on PyPy 7.3.10, fixing `issue 1515`_.
- Fix: the ``coverage lcov`` report did not properly implement the
``--fail-under=MIN`` option. This has been fixed.
- Refactor: added many type annotations, including a number of refactorings.
This should not affect outward behavior, but they were a bit invasive in some
places, so keep your eyes peeled for oddities.
- Refactor: removed the vestigial and long untested support for Jython and
IronPython.
.. _issue 1515: https://github.com/nedbat/coveragepy/issues/1515
.. _issue 1516: https://github.com/nedbat/coveragepy/issues/1516
.. _issue 1519: https://github.com/nedbat/coveragepy/issues/1519
.. _changes_7-0-1:
Version 7.0.1 โ 2022-12-23
--------------------------
- When checking if a file mapping resolved to a file that exists, we weren't
considering files in .whl files. This is now fixed, closing `issue 1511`_.
- File pattern rules were too strict, forbidding plus signs and curly braces in
directory and file names. This is now fixed, closing `issue 1513`_.
- Unusual Unicode or control characters in source files could prevent
reporting. This is now fixed, closing `issue 1512`_.
- The PyPy wheel now installs on PyPy 3.7, 3.8, and 3.9, closing `issue 1510`_.
.. _issue 1510: https://github.com/nedbat/coveragepy/issues/1510
.. _issue 1511: https://github.com/nedbat/coveragepy/issues/1511
.. _issue 1512: https://github.com/nedbat/coveragepy/issues/1512
.. _issue 1513: https://github.com/nedbat/coveragepy/issues/1513
.. _changes_7-0-0:
Version 7.0.0 โ 2022-12-18
--------------------------
Nothing new beyond 7.0.0b1.
.. _changes_7-0-0b1:
Version 7.0.0b1 โ 2022-12-03
----------------------------
A number of changes have been made to file path handling, including pattern
matching and path remapping with the ``[paths]`` setting (see
:ref:`config_paths`). These changes might affect you, and require you to
update your settings.
(This release includes the changes from `6.6.0b1`__, since 6.6.0 was never
released.)
__ https://coverage.readthedocs.io/en/latest/changes.html#changes-6-6-0b1
- Changes to file pattern matching, which might require updating your
configuration:
- Previously, ``*`` would incorrectly match directory separators, making
precise matching difficult. This is now fixed, closing `issue 1407`_.
- Now ``**`` matches any number of nested directories, including none.
- Improvements to combining data files when using the
:ref:`config_run_relative_files` setting, which might require updating your
configuration:
- During ``coverage combine``, relative file paths are implicitly combined
without needing a ``[paths]`` configuration setting. This also fixed
`issue 991`_.
- A ``[paths]`` setting like ``*/foo`` will now match ``foo/bar.py`` so that
relative file paths can be combined more easily.
- The :ref:`config_run_relative_files` setting is properly interpreted in
more places, fixing `issue 1280`_.
- When remapping file paths with ``[paths]``, a path will be remapped only if
the resulting path exists. The documentation has long said the prefix had to
exist, but it was never enforced. This fixes `issue 608`_, improves `issue
649`_, and closes `issue 757`_.
- Reporting operations now implicitly use the ``[paths]`` setting to remap file
paths within a single data file. Combining multiple files still requires the
``coverage combine`` step, but this simplifies some single-file situations.
Closes `issue 1212`_ and `issue 713`_.
- The ``coverage report`` command now has a ``--format=`` option. The original
style is now ``--format=text``, and is the default.
- Using ``--format=markdown`` will write the table in Markdown format, thanks
to `Steve Oswald `_, closing `issue 1418`_.
- Using ``--format=total`` will write a single total number to the
output. This can be useful for making badges or writing status updates.
- Combining data files with ``coverage combine`` now hashes the data files to
skip files that add no new information. This can reduce the time needed.
Many details affect the speed-up, but for coverage.py's own test suite,
combining is about 40% faster. Closes `issue 1483`_.
- When searching for completely un-executed files, coverage.py uses the
presence of ``__init__.py`` files to determine which directories have source
that could have been imported. However, `implicit namespace packages`_ don't
require ``__init__.py``. A new setting ``[report]
include_namespace_packages`` tells coverage.py to consider these directories
during reporting. Thanks to `Felix Horvat `_ for the
contribution. Closes `issue 1383`_ and `issue 1024`_.
- Fixed environment variable expansion in pyproject.toml files. It was overly
broad, causing errors outside of coverage.py settings, as described in `issue
1481`_ and `issue 1345`_. This is now fixed, but in rare cases will require
changing your pyproject.toml to quote non-string values that use environment
substitution.
- An empty file has a coverage total of 100%, but used to fail with
``--fail-under``. This has been fixed, closing `issue 1470`_.
- The text report table no longer writes out two separator lines if there are
no files listed in the table. One is plenty.
- Fixed a mis-measurement of a strange use of wildcard alternatives in
match/case statements, closing `issue 1421`_.
- Fixed internal logic that prevented coverage.py from running on
implementations other than CPython or PyPy (`issue 1474`_).
- The deprecated ``[run] note`` setting has been completely removed.
.. _implicit namespace packages: https://peps.python.org/pep-0420/
.. _issue 608: https://github.com/nedbat/coveragepy/issues/608
.. _issue 649: https://github.com/nedbat/coveragepy/issues/649
.. _issue 713: https://github.com/nedbat/coveragepy/issues/713
.. _issue 757: https://github.com/nedbat/coveragepy/issues/757
.. _issue 991: https://github.com/nedbat/coveragepy/issues/991
.. _issue 1024: https://github.com/nedbat/coveragepy/issues/1024
.. _issue 1212: https://github.com/nedbat/coveragepy/issues/1212
.. _issue 1280: https://github.com/nedbat/coveragepy/issues/1280
.. _issue 1345: https://github.com/nedbat/coveragepy/issues/1345
.. _issue 1383: https://github.com/nedbat/coveragepy/issues/1383
.. _issue 1407: https://github.com/nedbat/coveragepy/issues/1407
.. _issue 1418: https://github.com/nedbat/coveragepy/issues/1418
.. _issue 1421: https://github.com/nedbat/coveragepy/issues/1421
.. _issue 1470: https://github.com/nedbat/coveragepy/issues/1470
.. _issue 1474: https://github.com/nedbat/coveragepy/issues/1474
.. _issue 1481: https://github.com/nedbat/coveragepy/issues/1481
.. _issue 1483: https://github.com/nedbat/coveragepy/issues/1483
.. _pull 1387: https://github.com/nedbat/coveragepy/pull/1387
.. _pull 1479: https://github.com/nedbat/coveragepy/pull/1479
.. _changes_6-6-0b1:
Version 6.6.0b1 โ 2022-10-31
----------------------------
(Note: 6.6.0 final was never released. These changes are part of `7.0.0b1`__.)
__ https://coverage.readthedocs.io/en/latest/changes.html#changes-7-0-0b1
- Changes to file pattern matching, which might require updating your
configuration:
- Previously, ``*`` would incorrectly match directory separators, making
precise matching difficult. This is now fixed, closing `issue 1407`_.
- Now ``**`` matches any number of nested directories, including none.
- Improvements to combining data files when using the
:ref:`config_run_relative_files` setting:
- During ``coverage combine``, relative file paths are implicitly combined
without needing a ``[paths]`` configuration setting. This also fixed
`issue 991`_.
- A ``[paths]`` setting like ``*/foo`` will now match ``foo/bar.py`` so that
relative file paths can be combined more easily.
- The setting is properly interpreted in more places, fixing `issue 1280`_.
- Fixed environment variable expansion in pyproject.toml files. It was overly
broad, causing errors outside of coverage.py settings, as described in `issue
1481`_ and `issue 1345`_. This is now fixed, but in rare cases will require
changing your pyproject.toml to quote non-string values that use environment
substitution.
- Fixed internal logic that prevented coverage.py from running on
implementations other than CPython or PyPy (`issue 1474`_).
.. _issue 991: https://github.com/nedbat/coveragepy/issues/991
.. _issue 1280: https://github.com/nedbat/coveragepy/issues/1280
.. _issue 1345: https://github.com/nedbat/coveragepy/issues/1345
.. _issue 1407: https://github.com/nedbat/coveragepy/issues/1407
.. _issue 1474: https://github.com/nedbat/coveragepy/issues/1474
.. _issue 1481: https://github.com/nedbat/coveragepy/issues/1481
.. _changes_6-5-0:
Version 6.5.0 โ 2022-09-29
--------------------------
- The JSON report now includes details of which branches were taken, and which
are missing for each file. Thanks, `Christoph Blessing `_. Closes
`issue 1425`_.
- Starting with coverage.py 6.2, ``class`` statements were marked as a branch.
This wasn't right, and has been reverted, fixing `issue 1449`_. Note this
will very slightly reduce your coverage total if you are measuring branch
coverage.
- Packaging is now compliant with `PEP 517`_, closing `issue 1395`_.
- A new debug option ``--debug=pathmap`` shows details of the remapping of
paths that happens during combine due to the ``[paths]`` setting.
- Fix an internal problem with caching of invalid Python parsing. Found by
OSS-Fuzz, fixing their `bug 50381`_.
.. _bug 50381: https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=50381
.. _PEP 517: https://peps.python.org/pep-0517/
.. _issue 1395: https://github.com/nedbat/coveragepy/issues/1395
.. _issue 1425: https://github.com/nedbat/coveragepy/issues/1425
.. _issue 1449: https://github.com/nedbat/coveragepy/issues/1449
.. _pull 1438: https://github.com/nedbat/coveragepy/pull/1438
.. _changes_6-4-4:
Version 6.4.4 โ 2022-08-16
--------------------------
- Wheels are now provided for Python 3.11.
.. _changes_6-4-3:
Version 6.4.3 โ 2022-08-06
--------------------------
- Fix a failure when combining data files if the file names contained glob-like
patterns. Thanks, `Michael Krebs and Benjamin Schubert `_.
- Fix a messaging failure when combining Windows data files on a different
drive than the current directory, closing `issue 1428`_. Thanks, `Lorenzo
Micรฒ `_.
- Fix path calculations when running in the root directory, as you might do in
a Docker container. Thanks `Arthur Rio `_.
- Filtering in the HTML report wouldn't work when reloading the index page.
This is now fixed. Thanks, `Marc Legendre `_.
- Fix a problem with Cython code measurement, closing `issue 972`_. Thanks,
`Matus Valo `_.
.. _issue 972: https://github.com/nedbat/coveragepy/issues/972
.. _issue 1428: https://github.com/nedbat/coveragepy/issues/1428
.. _pull 1347: https://github.com/nedbat/coveragepy/pull/1347
.. _pull 1403: https://github.com/nedbat/coveragepy/issues/1403
.. _pull 1405: https://github.com/nedbat/coveragepy/issues/1405
.. _pull 1413: https://github.com/nedbat/coveragepy/issues/1413
.. _pull 1430: https://github.com/nedbat/coveragepy/pull/1430
.. _changes_6-4-2:
Version 6.4.2 โ 2022-07-12
--------------------------
- Updated for a small change in Python 3.11.0 beta 4: modules now start with a
line with line number 0, which is ignored. This line cannot be executed, so
coverage totals were thrown off. This line is now ignored by coverage.py,
but this also means that truly empty modules (like ``__init__.py``) have no
lines in them, rather than one phantom line. Fixes `issue 1419`_.
- Internal debugging data added to sys.modules is now an actual module, to
avoid confusing code that examines everything in sys.modules. Thanks,
`Yilei Yang `_.
.. _issue 1419: https://github.com/nedbat/coveragepy/issues/1419
.. _pull 1399: https://github.com/nedbat/coveragepy/pull/1399
.. _changes_6-4-1:
Version 6.4.1 โ 2022-06-02
--------------------------
- Greatly improved performance on PyPy, and other environments that need the
pure Python trace function. Thanks, Carl Friedrich Bolz-Tereick (`pull
1381`_ and `pull 1388`_). Slightly improved performance when using the C
trace function, as most environments do. Closes `issue 1339`_.
- The conditions for using tomllib from the standard library have been made
more precise, so that 3.11 alphas will continue to work. Closes `issue
1390`_.
.. _issue 1339: https://github.com/nedbat/coveragepy/issues/1339
.. _pull 1381: https://github.com/nedbat/coveragepy/pull/1381
.. _pull 1388: https://github.com/nedbat/coveragepy/pull/1388
.. _issue 1390: https://github.com/nedbat/coveragepy/issues/1390
.. _changes_64:
Version 6.4 โ 2022-05-22
------------------------
- A new setting, :ref:`config_run_sigterm`, controls whether a SIGTERM signal
handler is used. In 6.3, the signal handler was always installed, to capture
data at unusual process ends. Unfortunately, this introduced other problems
(see `issue 1310`_). Now the signal handler is only used if you opt-in by
setting ``[run] sigterm = true``.
- Small changes to the HTML report:
- Added links to next and previous file, and more keyboard shortcuts: ``[``
and ``]`` for next file and previous file; ``u`` for up to the index; and
``?`` to open/close the help panel. Thanks, `J. M. F. Tsang
`_.
- The time stamp and version are displayed at the top of the report. Thanks,
`Ammar Askar `_. Closes `issue 1351`_.
- A new debug option ``debug=sqldata`` adds more detail to ``debug=sql``,
logging all the data being written to the database.
- Previously, running ``coverage report`` (or any of the reporting commands) in
an empty directory would create a .coverage data file. Now they do not,
fixing `issue 1328`_.
- On Python 3.11, the ``[toml]`` extra no longer installs tomli, instead using
tomllib from the standard library. Thanks `Shantanu `_.
- In-memory CoverageData objects now properly update(), closing `issue 1323`_.
.. _issue 1310: https://github.com/nedbat/coveragepy/issues/1310
.. _issue 1323: https://github.com/nedbat/coveragepy/issues/1323
.. _issue 1328: https://github.com/nedbat/coveragepy/issues/1328
.. _issue 1351: https://github.com/nedbat/coveragepy/issues/1351
.. _pull 1354: https://github.com/nedbat/coveragepy/pull/1354
.. _pull 1359: https://github.com/nedbat/coveragepy/pull/1359
.. _pull 1364: https://github.com/nedbat/coveragepy/pull/1364
.. _changes_633:
Version 6.3.3 โ 2022-05-12
--------------------------
- Fix: Coverage.py now builds successfully on CPython 3.11 (3.11.0b1) again.
Closes `issue 1367`_. Some results for generators may have changed.
.. _issue 1367: https://github.com/nedbat/coveragepy/issues/1367
.. _changes_632:
Version 6.3.2 โ 2022-02-20
--------------------------
- Fix: adapt to pypy3.9's decorator tracing behavior. It now traces function
decorators like CPython 3.8: both the @-line and the def-line are traced.
Fixes `issue 1326`_.
- Debug: added ``pybehave`` to the list of :ref:`coverage debug `
and :ref:`cmd_run_debug` options.
- Fix: show an intelligible error message if ``--concurrency=multiprocessing``
is used without a configuration file. Closes `issue 1320`_.
.. _issue 1320: https://github.com/nedbat/coveragepy/issues/1320
.. _issue 1326: https://github.com/nedbat/coveragepy/issues/1326
.. _changes_631:
Version 6.3.1 โ 2022-02-01
--------------------------
- Fix: deadlocks could occur when terminating processes. Some of these
deadlocks (described in `issue 1310`_) are now fixed.
- Fix: a signal handler was being set from multiple threads, causing an error:
"ValueError: signal only works in main thread". This is now fixed, closing
`issue 1312`_.
- Fix: ``--precision`` on the command-line was being ignored while considering
``--fail-under``. This is now fixed, thanks to
`Marcelo Trylesinski `_.
- Fix: releases no longer provide 3.11.0-alpha wheels. Coverage.py uses CPython
internal fields which are moving during the alpha phase. Fixes `issue 1316`_.
.. _issue 1310: https://github.com/nedbat/coveragepy/issues/1310
.. _issue 1312: https://github.com/nedbat/coveragepy/issues/1312
.. _issue 1316: https://github.com/nedbat/coveragepy/issues/1316
.. _pull 1317: https://github.com/nedbat/coveragepy/pull/1317
.. _changes_63:
Version 6.3 โ 2022-01-25
------------------------
- Feature: Added the ``lcov`` command to generate reports in LCOV format.
Thanks, `Bradley Burns `_. Closes issues `587 `_
and `626 `_.
- Feature: the coverage data file can now be specified on the command line with
the ``--data-file`` option in any command that reads or writes data. This is
in addition to the existing ``COVERAGE_FILE`` environment variable. Closes
`issue 624`_. Thanks, `Nikita Bloshchanevich `_.
- Feature: coverage measurement data will now be written when a SIGTERM signal
is received by the process. This includes
:meth:`Process.terminate `,
and other ways to terminate a process. Currently this is only on Linux and
Mac; Windows is not supported. Fixes `issue 1307`_.
- Dropped support for Python 3.6, which reached end-of-life on 2021-12-23.
- Updated Python 3.11 support to 3.11.0a4, fixing `issue 1294`_.
- Fix: the coverage data file is now created in a more robust way, to avoid
problems when multiple processes are trying to write data at once. Fixes
issues `1303 `_ and `883 `_.
- Fix: a .gitignore file will only be written into the HTML report output
directory if the directory is empty. This should prevent certain unfortunate
accidents of writing the file where it is not wanted.
- Releases now have MacOS arm64 wheels for Apple Silicon, fixing `issue 1288`_.
.. _issue 587: https://github.com/nedbat/coveragepy/issues/587
.. _issue 624: https://github.com/nedbat/coveragepy/issues/624
.. _issue 626: https://github.com/nedbat/coveragepy/issues/626
.. _issue 883: https://github.com/nedbat/coveragepy/issues/883
.. _issue 1288: https://github.com/nedbat/coveragepy/issues/1288
.. _issue 1294: https://github.com/nedbat/coveragepy/issues/1294
.. _issue 1303: https://github.com/nedbat/coveragepy/issues/1303
.. _issue 1307: https://github.com/nedbat/coveragepy/issues/1307
.. _pull 1289: https://github.com/nedbat/coveragepy/pull/1289
.. _pull 1304: https://github.com/nedbat/coveragepy/pull/1304
.. _changes_62:
Version 6.2 โ 2021-11-26
------------------------
- Feature: Now the ``--concurrency`` setting can have a list of values, so that
threads and another lightweight threading package can be measured together,
such as ``--concurrency=gevent,thread``. Closes `issue 1012`_ and `issue
1082`_. This also means that ``thread`` must be explicitly specified in some
cases that used to be implicit such as ``--concurrency=multiprocessing``,
which must be changed to ``--concurrency=multiprocessing,thread``.
- Fix: A module specified as the ``source`` setting is imported during startup,
before the user program imports it. This could cause problems if the rest of
the program isn't ready yet. For example, `issue 1203`_ describes a Django
setting that is accessed before settings have been configured. Now the early
import is wrapped in a try/except so errors then don't stop execution.
- Fix: A colon in a decorator expression would cause an exclusion to end too
early, preventing the exclusion of the decorated function. This is now fixed.
- Fix: The HTML report now will not overwrite a .gitignore file that already
exists in the HTML output directory (follow-on for `issue 1244
`_).
- API: The exceptions raised by Coverage.py have been specialized, to provide
finer-grained catching of exceptions by third-party code.
- API: Using ``suffix=False`` when constructing a Coverage object with
multiprocessing wouldn't suppress the data file suffix (`issue 989`_). This
is now fixed.
- Debug: The ``coverage debug data`` command will now sniff out combinable data
files, and report on all of them.
- Debug: The ``coverage debug`` command used to accept a number of topics at a
time, and show all of them, though this was never documented. This no longer
works, to allow for command-line options in the future.
.. _issue 989: https://github.com/nedbat/coveragepy/issues/989
.. _issue 1012: https://github.com/nedbat/coveragepy/issues/1012
.. _issue 1082: https://github.com/nedbat/coveragepy/issues/1082
.. _issue 1203: https://github.com/nedbat/coveragepy/issues/1203
.. _issue 1244b: https://github.com/nedbat/coveragepy/issues/1244
.. _changes_612:
Version 6.1.2 โ 2021-11-10
--------------------------
- Python 3.11 is supported (tested with 3.11.0a2). One still-open issue has to
do with `exits through with-statements `_.
- Fix: When remapping file paths through the ``[paths]`` setting while
combining, the ``[run] relative_files`` setting was ignored, resulting in
absolute paths for remapped file names (`issue 1147`_). This is now fixed.
- Fix: Complex conditionals over excluded lines could have incorrectly reported
a missing branch (`issue 1271`_). This is now fixed.
- Fix: More exceptions are now handled when trying to parse source files for
reporting. Problems that used to terminate coverage.py can now be handled
with ``[report] ignore_errors``. This helps with plugins failing to read
files (`django_coverage_plugin issue 78`_).
- Fix: Removed another vestige of jQuery from the source tarball
(`issue 840 `_).
- Fix: Added a default value for a new-to-6.x argument of an internal class.
This unsupported class is being used by coveralls (`issue 1273`_). Although
I'd rather not "fix" unsupported interfaces, it's actually nicer with a
default value.
.. _django_coverage_plugin issue 78: https://github.com/nedbat/django_coverage_plugin/issues/78
.. _issue 840b: https://github.com/nedbat/coveragepy/issues/840
.. _issue 1147: https://github.com/nedbat/coveragepy/issues/1147
.. _issue 1270: https://github.com/nedbat/coveragepy/issues/1270
.. _issue 1271: https://github.com/nedbat/coveragepy/issues/1271
.. _issue 1273: https://github.com/nedbat/coveragepy/issues/1273
.. _changes_611:
Version 6.1.1 โ 2021-10-31
--------------------------
- Fix: The sticky header on the HTML report didn't work unless you had branch
coverage enabled. This is now fixed: the sticky header works for everyone.
(Do people still use coverage without branch measurement!? j/k)
- Fix: When using explicitly declared namespace packages, the "already imported
a file that will be measured" warning would be issued (`issue 888`_). This
is now fixed.
.. _issue 888: https://github.com/nedbat/coveragepy/issues/888
.. _changes_61:
Version 6.1 โ 2021-10-30
------------------------
- Deprecated: The ``annotate`` command and the ``Coverage.annotate`` function
will be removed in a future version, unless people let me know that they are
using it. Instead, the ``html`` command gives better-looking (and more
accurate) output, and the ``report -m`` command will tell you line numbers of
missing lines. Please get in touch if you have a reason to use ``annotate``
over those better options: ned@nedbatchelder.com.
- Feature: Coverage now sets an environment variable, ``COVERAGE_RUN`` when
running your code with the ``coverage run`` command. The value is not
important, and may change in the future. Closes `issue 553`_.
- Feature: The HTML report pages for Python source files now have a sticky
header so the file name and controls are always visible.
- Feature: The ``xml`` and ``json`` commands now describe what they wrote
where.
- Feature: The ``html``, ``combine``, ``xml``, and ``json`` commands all accept
a ``-q/--quiet`` option to suppress the messages they write to stdout about
what they are doing (`issue 1254`_).
- Feature: The ``html`` command writes a ``.gitignore`` file into the HTML
output directory, to prevent the report from being committed to git. If you
want to commit it, you will need to delete that file. Closes `issue 1244`_.
- Feature: Added support for PyPy 3.8.
- Fix: More generated code is now excluded from measurement. Code such as
`attrs`_ boilerplate, or doctest code, was being measured though the
synthetic line numbers meant they were never reported. Once Cython was
involved though, the generated .so files were parsed as Python, raising
syntax errors, as reported in `issue 1160`_. This is now fixed.
- Fix: When sorting human-readable names, numeric components are sorted
correctly: file10.py will appear after file9.py. This applies to file names,
module names, environment variables, and test contexts.
- Performance: Branch coverage measurement is faster, though you might only
notice on code that is executed many times, such as long-running loops.
- Build: jQuery is no longer used or vendored (`issue 840`_ and `issue 1118`_).
Huge thanks to Nils Kattenbeck (septatrix) for the conversion to vanilla
JavaScript in `pull request 1248`_.
.. _issue 553: https://github.com/nedbat/coveragepy/issues/553
.. _issue 840: https://github.com/nedbat/coveragepy/issues/840
.. _issue 1118: https://github.com/nedbat/coveragepy/issues/1118
.. _issue 1160: https://github.com/nedbat/coveragepy/issues/1160
.. _issue 1244: https://github.com/nedbat/coveragepy/issues/1244
.. _pull request 1248: https://github.com/nedbat/coveragepy/pull/1248
.. _issue 1254: https://github.com/nedbat/coveragepy/issues/1254
.. _attrs: https://www.attrs.org/
.. _changes_602:
Version 6.0.2 โ 2021-10-11
--------------------------
- Namespace packages being measured weren't properly handled by the new code
that ignores third-party packages. If the namespace package was installed, it
was ignored as a third-party package. That problem (`issue 1231`_) is now
fixed.
- Packages named as "source packages" (with ``source``, or ``source_pkgs``, or
pytest-cov's ``--cov``) might have been only partially measured. Their
top-level statements could be marked as un-executed, because they were
imported by coverage.py before measurement began (`issue 1232`_). This is
now fixed, but the package will be imported twice, once by coverage.py, then
again by your test suite. This could cause problems if importing the package
has side effects.
- The :meth:`.CoverageData.contexts_by_lineno` method was documented to return
a dict, but was returning a defaultdict. Now it returns a plain dict. It
also no longer returns negative numbered keys.
.. _issue 1231: https://github.com/nedbat/coveragepy/issues/1231
.. _issue 1232: https://github.com/nedbat/coveragepy/issues/1232
.. _changes_601:
Version 6.0.1 โ 2021-10-06
--------------------------
- In 6.0, the coverage.py exceptions moved from coverage.misc to
coverage.exceptions. These exceptions are not part of the public supported
API, CoverageException is. But a number of other third-party packages were
importing the exceptions from coverage.misc, so they are now available from
there again (`issue 1226`_).
- Changed an internal detail of how tomli is imported, so that tomli can use
coverage.py for their own test suite (`issue 1228`_).
- Defend against an obscure possibility under code obfuscation, where a
function can have an argument called "self", but no local named "self"
(`pull request 1210`_). Thanks, Ben Carlsson.
.. _pull request 1210: https://github.com/nedbat/coveragepy/pull/1210
.. _issue 1226: https://github.com/nedbat/coveragepy/issues/1226
.. _issue 1228: https://github.com/nedbat/coveragepy/issues/1228
.. _changes_60:
Version 6.0 โ 2021-10-03
------------------------
- The ``coverage html`` command now prints a message indicating where the HTML
report was written. Fixes `issue 1195`_.
- The ``coverage combine`` command now prints messages indicating each data
file being combined. Fixes `issue 1105`_.
- The HTML report now includes a sentence about skipped files due to
``skip_covered`` or ``skip_empty`` settings. Fixes `issue 1163`_.
- Unrecognized options in the configuration file are no longer errors. They are
now warnings, to ease the use of coverage across versions. Fixes `issue
1035`_.
- Fix handling of exceptions through context managers in Python 3.10. A missing
exception is no longer considered a missing branch from the with statement.
Fixes `issue 1205`_.
- Fix another rarer instance of "Error binding parameter 0 - probably
unsupported type." (`issue 1010 `_).
- Creating a directory for the coverage data file now is safer against
conflicts when two coverage runs happen simultaneously (`pull 1220`_).
Thanks, Clรฉment Pit-Claudel.
.. _issue 1010b: https://github.com/nedbat/coveragepy/issues/1010
.. _issue 1035: https://github.com/nedbat/coveragepy/issues/1035
.. _issue 1105: https://github.com/nedbat/coveragepy/issues/1105
.. _issue 1163: https://github.com/nedbat/coveragepy/issues/1163
.. _issue 1195: https://github.com/nedbat/coveragepy/issues/1195
.. _issue 1205: https://github.com/nedbat/coveragepy/issues/1205
.. _pull 1220: https://github.com/nedbat/coveragepy/pull/1220
.. _changes_60b1:
Version 6.0b1 โ 2021-07-18
--------------------------
- Dropped support for Python 2.7, PyPy 2, and Python 3.5.
- Added support for the Python 3.10 ``match/case`` syntax.
- Data collection is now thread-safe. There may have been rare instances of
exceptions raised in multi-threaded programs.
- Plugins (like the `Django coverage plugin`_) were generating "Already
imported a file that will be measured" warnings about Django itself. These
have been fixed, closing `issue 1150`_.
- Warnings generated by coverage.py are now real Python warnings.
- Using ``--fail-under=100`` with coverage near 100% could result in the
self-contradictory message :code:`total of 100 is less than fail-under=100`.
This bug (`issue 1168`_) is now fixed.
- The ``COVERAGE_DEBUG_FILE`` environment variable now accepts ``stdout`` and
``stderr`` to write to those destinations.
- TOML parsing now uses the `tomli`_ library.
- Some minor changes to usually invisible details of the HTML report:
- Use a modern hash algorithm when fingerprinting, for high-security
environments (`issue 1189`_). When generating the HTML report, we save the
hash of the data, to avoid regenerating an unchanged HTML page. We used to
use MD5 to generate the hash, and now use SHA-3-256. This was never a
security concern, but security scanners would notice the MD5 algorithm and
raise a false alarm.
- Change how report file names are generated, to avoid leading underscores
(`issue 1167`_), to avoid rare file name collisions (`issue 584`_), and to
avoid file names becoming too long (`issue 580`_).
.. _Django coverage plugin: https://pypi.org/project/django-coverage-plugin/
.. _issue 580: https://github.com/nedbat/coveragepy/issues/580
.. _issue 584: https://github.com/nedbat/coveragepy/issues/584
.. _issue 1150: https://github.com/nedbat/coveragepy/issues/1150
.. _issue 1167: https://github.com/nedbat/coveragepy/issues/1167
.. _issue 1168: https://github.com/nedbat/coveragepy/issues/1168
.. _issue 1189: https://github.com/nedbat/coveragepy/issues/1189
.. _tomli: https://pypi.org/project/tomli/
.. _changes_56b1:
Version 5.6b1 โ 2021-04-13
--------------------------
Note: 5.6 final was never released. These changes are part of 6.0.
- Third-party packages are now ignored in coverage reporting. This solves a
few problems:
- Coverage will no longer report about other people's code (`issue 876`_).
This is true even when using ``--source=.`` with a venv in the current
directory.
- Coverage will no longer generate "Already imported a file that will be
measured" warnings about coverage itself (`issue 905`_).
- The HTML report uses j/k to move up and down among the highlighted chunks of
code. They used to highlight the current chunk, but 5.0 broke that behavior.
Now the highlighting is working again.
- The JSON report now includes ``percent_covered_display``, a string with the
total percentage, rounded to the same number of decimal places as the other
reports' totals.
.. _issue 876: https://github.com/nedbat/coveragepy/issues/876
.. _issue 905: https://github.com/nedbat/coveragepy/issues/905
.. _changes_55:
Version 5.5 โ 2021-02-28
------------------------
- ``coverage combine`` has a new option, ``--keep`` to keep the original data
files after combining them. The default is still to delete the files after
they have been combined. This was requested in `issue 1108`_ and implemented
in `pull request 1110`_. Thanks, รric Lariviรจre.
- When reporting missing branches in ``coverage report``, branches aren't
reported that jump to missing lines. This adds to the long-standing behavior
of not reporting branches from missing lines. Now branches are only reported
if both the source and destination lines are executed. Closes both `issue
1065`_ and `issue 955`_.
- Minor improvements to the HTML report:
- The state of the line visibility selector buttons is saved in local storage
so you don't have to fiddle with them so often, fixing `issue 1123`_.
- It has a little more room for line numbers so that 4-digit numbers work
well, fixing `issue 1124`_.
- Improved the error message when combining line and branch data, so that users
will be more likely to understand what's happening, closing `issue 803`_.
.. _issue 803: https://github.com/nedbat/coveragepy/issues/803
.. _issue 955: https://github.com/nedbat/coveragepy/issues/955
.. _issue 1065: https://github.com/nedbat/coveragepy/issues/1065
.. _issue 1108: https://github.com/nedbat/coveragepy/issues/1108
.. _pull request 1110: https://github.com/nedbat/coveragepy/pull/1110
.. _issue 1123: https://github.com/nedbat/coveragepy/issues/1123
.. _issue 1124: https://github.com/nedbat/coveragepy/issues/1124
.. _changes_54:
Version 5.4 โ 2021-01-24
------------------------
- The text report produced by ``coverage report`` now always outputs a TOTAL
line, even if only one Python file is reported. This makes regex parsing
of the output easier. Thanks, Judson Neer. This had been requested a number
of times (`issue 1086`_, `issue 922`_, `issue 732`_).
- The ``skip_covered`` and ``skip_empty`` settings in the configuration file
can now be specified in the ``[html]`` section, so that text reports and HTML
reports can use separate settings. The HTML report will still use the
``[report]`` settings if there isn't a value in the ``[html]`` section.
Closes `issue 1090`_.
- Combining files on Windows across drives now works properly, fixing `issue
577`_. Thanks, `Valentin Lab `_.
- Fix an obscure warning from deep in the decimal module, as reported in
`issue 1084`_.
- Update to support Python 3.10 alphas in progress, including `PEP 626: Precise
line numbers for debugging and other tools `_.
.. _issue 577: https://github.com/nedbat/coveragepy/issues/577
.. _issue 732: https://github.com/nedbat/coveragepy/issues/732
.. _issue 922: https://github.com/nedbat/coveragepy/issues/922
.. _issue 1084: https://github.com/nedbat/coveragepy/issues/1084
.. _issue 1086: https://github.com/nedbat/coveragepy/issues/1086
.. _issue 1090: https://github.com/nedbat/coveragepy/issues/1090
.. _pr1080: https://github.com/nedbat/coveragepy/pull/1080
.. _pep626: https://www.python.org/dev/peps/pep-0626/
.. _changes_531:
Version 5.3.1 โ 2020-12-19
--------------------------
- When using ``--source`` on a large source tree, v5.x was slower than previous
versions. This performance regression is now fixed, closing `issue 1037`_.
- Mysterious SQLite errors can happen on PyPy, as reported in `issue 1010`_. An
immediate retry seems to fix the problem, although it is an unsatisfying
solution.
- The HTML report now saves the sort order in a more widely supported way,
fixing `issue 986`_. Thanks, Sebastiรกn Ramรญrez (`pull request 1066`_).
- The HTML report pages now have a :ref:`Sleepy Snake ` favicon.
- Wheels are now provided for manylinux2010, and for PyPy3 (pp36 and pp37).
- Continuous integration has moved from Travis and AppVeyor to GitHub Actions.
.. _issue 986: https://github.com/nedbat/coveragepy/issues/986
.. _issue 1037: https://github.com/nedbat/coveragepy/issues/1037
.. _issue 1010: https://github.com/nedbat/coveragepy/issues/1010
.. _pull request 1066: https://github.com/nedbat/coveragepy/pull/1066
.. _changes_53:
Version 5.3 โ 2020-09-13
------------------------
- The ``source`` setting has always been interpreted as either a file path or a
module, depending on which existed. If both interpretations were valid, it
was assumed to be a file path. The new ``source_pkgs`` setting can be used
to name a package to disambiguate this case. Thanks, Thomas Grainger. Fixes
`issue 268`_.
- If a plugin was disabled due to an exception, we used to still try to record
its information, causing an exception, as reported in `issue 1011`_. This is
now fixed.
.. _issue 268: https://github.com/nedbat/coveragepy/issues/268
.. _issue 1011: https://github.com/nedbat/coveragepy/issues/1011
.. endchangesinclude
Older changes
-------------
The complete history is available in the `coverage.py docs`__.
__ https://coverage.readthedocs.io/en/latest/changes.html
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/CITATION.cff 0000644 0001751 0001751 00000001771 15073731535 014752 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
cff-version: 1.2.0
title: "Coverage.py: The code coverage tool for Python"
message: >-
If you use this software, please cite it using the metadata from this file.
type: software
authors:
- family-names: Batchelder
given-names: Ned
orcid: https://orcid.org/0009-0006-2659-884X
- name: "Contributors to Coverage.py"
repository-code: "https://github.com/nedbat/coveragepy"
url: "https://coverage.readthedocs.io/"
abstract: >-
Coverage.py is a tool for measuring code coverage of Python programs. It monitors your program,
noting which parts of the code have been executed, then analyzes the source to identify code
that could have been executed but was not.
Coverage measurement is typically used to gauge the effectiveness of tests. It can show which
parts of your code are being exercised by tests, and which are not.
license: Apache-2.0
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/CONTRIBUTORS.txt 0000644 0001751 0001751 00000007312 15073731535 015553 0 ustar 00runner runner Coverage.py was originally written by Gareth Rees, and since 2004 has been
extended and maintained by Ned Batchelder.
Other contributions, including writing code, updating docs, and submitting
useful bug reports, have been made by:
Abdeali Kothari
Adam Turner
Adi Roiban
Agbonze O. Jeremiah
Albertas Agejevas
Aleksi Torhamo
Alex Gaynor
Alex Groce
Alex Sandro
Alexander Todorov
Alexander Walters
Alpha Chen
Ammar Askar
Anders Kaseorg
Andrew Hoos
Anthony Sottile
Arcadiy Ivanov
Arkady Gilinsky
Aron Griffis
Artem Dayneko
Arthur Deygin
Arthur Rio
Asher Foa
Ask Hjorth Larsen
Ben Carlsson
Ben Finney
Benjamin Parzella
Benjamin Schubert
Bernรกt Gรกbor
Bill Hart
Brad Smith
Bradley Burns
Brandon Rhodes
Brett Cannon
Brian Grohe
Bruno Oliveira
Bruno P. Kinoshita
Bruno Rodrigues dos Santos
Buck Evan
Buck Golemon
Calen Pennington
Carl Friedrich Bolz-Tereick
Carl Gieringer
Catherine Proulx
Charles Chan
Chris Adams
Chris Jerdonek
Chris Rose
Chris Warrick
Christian Clauss
Christian Heimes
Christine Lytwynec
Christoph Blessing
Christoph Zwerschke
Christopher Pickering
Clรฉment Pit-Claudel
Conrad Ho
Cosimo Lupo
Dan Hemberger
Dan Riti
Dan Wandschneider
Danek Duvall
Daniel Diniz
Daniel Hahler
Danny Allen
David Christian
David MacIver
David Stanek
David Szotten
Dennis Sweeney
Detlev Offenbach
Devin Jeanpierre
Dirk Thomas
Dmitry Shishov
Dmitry Trofimov
Edgar Ramรญrez Mondragรณn
Eduardo Schettino
Edward Loper
Eli Skeggs
Emil Madsen
รric Lariviรจre
Federico Bond
Felix Horvat
Finn Womack
Frazer McLean
Geoff Bache
George Paci
George Song
George-Cristian Bรฎrzan
Greg Rogers
Guido van Rossum
Guillaume Chazarain
Guillaume Pujol
Henry Schreiner
Holger Krekel
Hugo van Kemenade
Ian Moore
Ilia Meerovich
Imri Goldberg
Ionel Cristian Mฤrieศ
Ivan Ciuvalschii
J. M. F. Tsang
JT Olds
Jacqueline Lee
Jakub Wilk
James Valleroy
Jan Kรผhle
Jan Rusak
Janakarajan Natarajan
Jeremy Fleischman
Jerin Peter George
Jessamyn Smith
Joanna Ejzel
Joe Doherty
Joe Jevnik
John Vandenberg
Jon Chappell
Jon Dufresne
Joseph Tate
Josh Williams
Judson Neer
Julian Berman
Julien Voisin
Justas Sadzeviฤius
Karthikeyan Singaravelan
Kassandra Keeton
Ken Schackart
Kevin Brown-Silva
Kjell Braden
Krystian Kichewko
Kumar Aditya
Kyle Altendorf
Lars Hupfeldt Nielsen
Latrice Wilgus
Leonardo Pistone
Lewis Gaul
Lex Berezhny
Liam DeVoe
LiuYinCarl
Loรฏc Dachary
Lorenzo Micรฒ
Louis Heredero
Luis Nell
ลukasz Stolcman
Maciej Kowalczyk
Manuel Jacob
Marc Abramowitz
Marc Gibbons
Marc Legendre
Marcelo Trylesinski
Marco Ricci
Marcus Cobden
Mariatta
Marius Gedminas
Mark van der Wal
Martin Fuzzey
Mathieu Kniewallner
Matt Bachmann
Matthew Boehm
Matthew Desmarais
Matus Valo
Max Linke
Mayank Singhal
Michael Bell
Michael Krebs
Michaล Bultrowicz
Michaล Gรณrny
Mickie Betz
Mike Fiedler
Min ho Kim
Nathan Goldbaum
Nathan Land
Naveen Srinivasan
Naveen Yadav
Neil Pilgrim
Nicholas Nadeau
Nick Drozd
Nikita Bloshchanevich
Nikita Sobolev
Nils Kattenbeck
Noel O'Boyle
Oleg Hรถfling
Oleh Krehel
Olivier Grisel
Ori Avtalion
Pablo Carballo
Pankaj Pandey
Patrick Mezard
Paul Timmins
Pavel Tsialnou
Peter Baughman
Peter Ebden
Peter Portante
Phebe Polk
Reya B
Ricardo Newbery
Robert Harris
Rodrigue Cloutier
Roger Hu
Roland Illig
Ross Lawley
Roy Williams
Russell Keith-Magee
S. Y. Lee
Salvatore Zagaria
Sandra Martocchia
Scott Belden
Sebastiรกn Ramรญrez
Sergey B Kirpichev
Shantanu
Sigve Tjora
Simon Willison
Stan Hu
Stanisลaw Pitucha
Stefan Behnel
Stephan Deibel
Stephan Richter
Stephen Finucane
Steve Dower
Steve Leonard
Steve Oswald
Steve Peak
Sviatoslav Sydorenko
Tanaydin Sirin
Teake Nutma
Ted Wexler
Thijs Triemstra
Thomas Grainger
Timo Furrer
Titus Brown
Tom Gurion
Tomas Uribe
Valentin Lab
Ville Skyttรค
Vince Salvino
Wonwin McBrootles
Xie Yanbo
Yilei "Dolee" Yang
Yury Selivanov
Zac Hatfield-Dodds
Zack Weinberg
Zooko Wilcox-O'Hearn
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/LICENSE.txt 0000644 0001751 0001751 00000023676 15073731535 014713 0 ustar 00runner runner
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/MANIFEST.in 0000644 0001751 0001751 00000002475 15073731535 014620 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
# MANIFEST.in file for coverage.py
# This file includes everything needed to recreate the entire project, even
# though many of these files are not installed by setup.py. Unpacking the
# .tar.gz source distribution would give you everything needed to continue
# developing the project. "pip install" will not install many of these files.
include .editorconfig
include .git-blame-ignore-revs
include .ignore
include .pre-commit-config.yaml
include .readthedocs.yaml
include CHANGES.rst
include CITATION.cff
include CONTRIBUTORS.txt
include LICENSE.txt
include MANIFEST.in
include Makefile
include NOTICE.txt
include README.rst
include __main__.py
include howto.txt
include igor.py
include metacov.ini
include setup.py
include tox.ini
recursive-include ci *
recursive-include lab *
recursive-include .github *
recursive-include coverage *.pyi
recursive-include coverage/ctracer *.c *.h
recursive-include doc *.py *.in *.pip *.rst *.txt *.png
recursive-include doc/_static *
prune doc/_build
prune doc/_spell
recursive-include requirements *.in *.pip
recursive-include tests *.py *.tok
recursive-include tests/gold *
recursive-include tests js/* qunit/*
prune tests/eggsrc/build
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/Makefile 0000644 0001751 0001751 00000025227 15073731535 014522 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
# Makefile for utility work on coverage.py.
.DEFAULT_GOAL := help
##@ Utilities
.PHONY: help _clean_platform debug_clean clean_platform clean sterile install
help: ## Show this help.
@# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/
@echo Available targets:
@awk -F ':.*##' '/^[^: ]+:.*##/{printf " \033[1m%-20s\033[m %s\n",$$1,$$2} /^##@/{printf "\n%s\n",substr($$0,5)}' $(MAKEFILE_LIST)
_clean_platform:
@rm -f *.so */*.so
@rm -f *.pyd */*.pyd
@rm -rf __pycache__ */__pycache__ */*/__pycache__ */*/*/__pycache__ */*/*/*/__pycache__ */*/*/*/*/__pycache__
@rm -f *.pyc */*.pyc */*/*.pyc */*/*/*.pyc */*/*/*/*.pyc */*/*/*/*/*.pyc
@rm -f *.pyo */*.pyo */*/*.pyo */*/*/*.pyo */*/*/*/*.pyo */*/*/*/*/*.pyo
@rm -f .DS_Store */.DS_Store */*/.DS_Store */*/*/.DS_Store */*/*/*/.DS_Store
debug_clean: ## Delete various debugging artifacts.
@rm -rf /tmp/dis $$COVERAGE_DEBUG_FILE
clean: debug_clean _clean_platform ## Remove artifacts of test execution, installation, etc.
@echo "Cleaning..."
@-pip uninstall -yq coverage
@mkdir -p build # so the chmod won't fail if build doesn't exist
@chmod -R 777 build
@rm -rf build coverage.egg-info dist htmlcov
@rm -f *.bak */*.bak */*/*.bak */*/*/*.bak */*/*/*/*.bak */*/*/*/*/*.bak
@rm -f coverage/*,cover
@rm -f MANIFEST
@rm -f .coverage .coverage.* .metacov*
@rm -f coverage.xml coverage.json
@rm -f .tox/*/lib/*/site-packages/zzz_metacov.pth
@rm -f */.coverage */*/.coverage */*/*/.coverage */*/*/*/.coverage */*/*/*/*/.coverage */*/*/*/*/*/.coverage
@rm -f tests/covmain.zip tests/zipmods.zip tests/zip1.zip
@rm -rf doc/_build doc/_spell doc/sample_html_beta
@rm -rf tmp
@rm -rf .*cache */.*cache */*/.*cache */*/*/.*cache .hypothesis
@rm -rf tests/actual
@-make -C tests/gold/html clean
sterile: clean ## Remove all non-controlled content, even if expensive.
rm -rf .tox
rm -f cheats.txt
# For installing development tooling, use uv if it's available, otherwise pip.
HAS_UV := $(shell command -v uv 2>/dev/null)
ifdef HAS_UV
INSTALL := uv pip sync
else
INSTALL := python -m pip install -r
endif
install: ## Install the developer tools.
$(INSTALL) requirements/dev.pip
##@ Tests and quality checks
.PHONY: lint mypy precommit quality test
lint: ## Run linters and checkers.
tox -q -e lint
mypy: ## Run the type checker.
tox -q -e mypy
precommit: ## Run the pre-commit checks.
PYTHONWARNDEFAULTENCODING= pre-commit run --all-files
quality: lint mypy precommit ## Run all the quality checks.
test: ## Run the test suite.
tox -q -m py
##@ Metacov: coverage measurement of coverage.py itself
# See metacov.ini for details.
.PHONY: metacov metahtml
metacov: ## Run meta-coverage, measuring ourself.
COVERAGE_COVERAGE=yes tox -q $(ARGS)
metahtml: ## Produce meta-coverage HTML reports.
tox exec -q $(ARGS) -- python3 igor.py combine_html
##@ Requirements management
# When updating requirements, a few rules to follow:
#
# 1) Don't install more than one .pip file at once. Always use pip-compile to
# combine .in files onto a single .pip file that can be installed where needed.
#
# 2) Check manual pins before `make upgrade` to see if they can be removed. Look
# in requirements/pins.pip, and search for "windows" in .in files to find pins
# and extra requirements that have been needed, but might be obsolete.
.PHONY: upgrade upgrade_one _upgrade diff_upgrade
DOCBIN = .tox/doc/bin
# PYVERSION to use for kitting, based on cibuildwheel's requirements.
KITVER = py311
KITBIN = .tox/$(KITVER)/bin
$(KITBIN):
tox -q -e $(KITVER) --notest
PIP_COMPILE = uv pip compile -q --universal ${COMPILE_OPTS}
upgrade: ## Update the *.pip files with the latest packages satisfying *.in files.
$(MAKE) _upgrade COMPILE_OPTS="--upgrade"
upgrade_one: ## Update the *.pip files for one package. `make upgrade_one package=...`
@test -n "$(package)" || { echo "\nUsage: make upgrade-one package=...\n"; exit 1; }
$(MAKE) _upgrade COMPILE_OPTS="--upgrade-package $(package)"
_upgrade: export UV_CUSTOM_COMPILE_COMMAND=make upgrade
_upgrade: $(DOCBIN) $(KITBIN)
$(PIP_COMPILE) -o requirements/pip.pip requirements/pip.in
$(PIP_COMPILE) -o requirements/pytest.pip requirements/pytest.in
$(PIP_COMPILE) -p $(KITBIN)/python3 -o requirements/kit.pip requirements/kit.in
$(PIP_COMPILE) -o requirements/tox.pip requirements/tox.in
$(PIP_COMPILE) -o requirements/dev.pip requirements/dev.in
$(PIP_COMPILE) -o requirements/light-threads.pip requirements/light-threads.in
$(PIP_COMPILE) -o requirements/mypy.pip requirements/mypy.in
$(PIP_COMPILE) -p $(DOCBIN)/python3 -o doc/requirements.pip doc/requirements.in
PYTHONWARNDEFAULTENCODING= pre-commit autoupdate
diff_upgrade: ## Summarize the last `make upgrade`.
@# The sort flags sort by the package name first, then by the -/+, and
@# sort by version numbers, so we get a summary with lines like this:
@# -bashlex==0.16
@# +bashlex==0.17
@# -build==0.9.0
@# +build==0.10.0
@git diff -U0 | grep -v '^@' | grep == | sort -k1.2,1.99 -k1.1,1.1r -u -V
##@ Pre-builds for prepping the code
.PHONY: css workflows prebuild
CSS = coverage/htmlfiles/style.css
SCSS = coverage/htmlfiles/style.scss
css: $(CSS) ## Compile .scss into .css.
$(CSS): $(SCSS)
pysassc --style=compact $(SCSS) $@
cp $@ tests/gold/html/styled
workflows: ## Run cog on the workflows to keep them up-to-date.
python -m cogapp -crP .github/workflows/*.yml
prebuild: css workflows cogdoc ## One command for all source prep.
##@ Sample HTML reports
.PHONY: _sample_cog_html sample_html sample_html_beta
_sample_cog_html: clean
python -m pip install -e .
cd ~/cog; \
rm -rf htmlcov; \
PYTEST_ADDOPTS= coverage run --branch --source=cogapp -m pytest -k CogTestsInMemory; \
coverage combine; \
coverage html
sample_html: _sample_cog_html ## Generate sample HTML report.
rm -f doc/sample_html/*.*
cp -r ~/cog/htmlcov/ doc/sample_html/
rm doc/sample_html/.gitignore
sample_html_beta: _sample_cog_html ## Generate sample HTML report for a beta release.
rm -f doc/sample_html_beta/*.*
cp -r ~/cog/htmlcov/ doc/sample_html_beta/
rm doc/sample_html_beta/.gitignore
##@ Kitting: making releases
.PHONY: release_version edit_for_release cheats relbranch relcommit1 relcommit2
.PHONY: kit pypi_upload test_upload kit_local build_kits update_rtd
.PHONY: tag bump_version
REPO_OWNER = nedbat/coveragepy
RTD_PROJECT = coverage
release_version: #: Update the version for a release.
python igor.py release_version
edit_for_release: #: Edit sources to insert release facts (see howto.txt).
python igor.py edit_for_release
cheats: ## Create some useful snippets for releasing.
python igor.py cheats | tee cheats.txt
relbranch: #: Create the branch for releasing (see howto.txt).
git switch -c nedbat/release-$$(date +%Y%m%d-%H%M%S)
relcommit1: #: Commit the first release changes (see howto.txt).
git commit -am "docs: prep for $$(python setup.py --version)"
relcommit2: #: Commit the latest sample HTML report (see howto.txt).
git add doc/sample_html
git commit -am "docs: sample HTML for $$(python setup.py --version)"
kit: ## Make the source distribution.
python -m build
pypi_upload: ## Upload the built distributions to PyPI.
python ci/trigger_action.py $(REPO_OWNER) publish-pypi
@echo "Use that^ URL to approve the upload"
test_upload: ## Upload the distributions to PyPI's testing server.
python ci/trigger_action.py $(REPO_OWNER) publish-testpypi
@echo "Use that^ URL to approve the upload"
kit_local:
# pip.conf looks like this:
# [global]
# find-links = file:///Users/ned/Downloads/local_pypi
cp -v dist/* `awk -F "//" '/find-links/ {print $$2}' ~/.pip/pip.conf`
# pip caches wheels of things it has installed. Clean them out so we
# don't go crazy trying to figure out why our new code isn't installing.
find ~/Library/Caches/pip/wheels -name 'coverage-*' -delete
build_kits: ## Trigger GitHub to build kits.
python ci/trigger_action.py $(REPO_OWNER) build-kits
tag: #: Make a git tag with the version number (see howto.txt).
git tag -s -m "Version $$(python setup.py --version)" $$(python setup.py --version)
git push --follow-tags
update_rtd: #: Update ReadTheDocs with the versions to show
python ci/update_rtfd.py $(RTD_PROJECT)
bump_version: #: Edit sources to bump the version after a release (see howto.txt).
git switch -c nedbat/bump-version
python igor.py bump_version
git commit -a -m "build: bump version to $$(python setup.py --version | sed 's/a.*//')"
git push -u origin @
##@ Documentation
.PHONY: cogdoc dochtml docdev docspell
SPHINXOPTS = -aE
SPHINXBUILD = $(DOCBIN)/sphinx-build $(SPHINXOPTS)
SPHINXAUTOBUILD = $(DOCBIN)/sphinx-autobuild --port 9876 --ignore '.git/**' --open-browser
$(DOCBIN):
tox -q -e doc --notest
cogdoc: $(DOCBIN) ## Run docs through cog.
$(DOCBIN)/python -m cogapp -crP --verbosity=1 doc/*.rst doc/*/*.rst
dochtml: cogdoc $(DOCBIN) ## Build the docs HTML output.
$(SPHINXBUILD) -b html doc doc/_build/html
@echo "Start at: doc/_build/html/index.html"
docdev: dochtml ## Build docs, and auto-watch for changes.
PATH=$(DOCBIN):$(PATH) $(SPHINXAUTOBUILD) -b html doc doc/_build/html
docspell: $(DOCBIN) ## Run the spell checker on the docs.
# Very mac-specific...
PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.dylib $(SPHINXBUILD) -b spelling doc doc/_spell
##@ Publishing docs
.PHONY: publish publishbeta github_releases comment_on_fixes
WEBHOME = ~/web/stellated
WEBSAMPLE = $(WEBHOME)/files/sample_coverage_html
WEBSAMPLEBETA = $(WEBHOME)/files/sample_coverage_html_beta
publish: ## Publish the sample HTML report.
rm -f $(WEBSAMPLE)/*.*
mkdir -p $(WEBSAMPLE)
cp doc/sample_html/*.* $(WEBSAMPLE)
publishbeta:
rm -f $(WEBSAMPLEBETA)/*.*
mkdir -p $(WEBSAMPLEBETA)
cp doc/sample_html_beta/*.* $(WEBSAMPLEBETA)
CHANGES_MD = tmp/rst_rst/changes.md
SCRIV_SOURCE = tmp/only-changes.md
$(CHANGES_MD): CHANGES.rst $(DOCBIN)
$(SPHINXBUILD) -b rst doc tmp/rst_rst
pandoc -frst -tmarkdown_strict --markdown-headings=atx --wrap=none tmp/rst_rst/changes.rst > $(CHANGES_MD)
$(SCRIV_SOURCE): $(CHANGES_MD)
@# Trim parts of the file that aren't changelog entries.
sed -n -e '/## Version/,/## Earlier/p' < $(CHANGES_MD) > tmp/trimmed.md
@# Replace sphinx references with published URLs.
sed -r -e 's@]\(([a-zA-Z0-9_]+)\.rst#([^)]+)\)@](https://coverage.readthedocs.io/en/latest/\1.html#\2)@g' < tmp/trimmed.md > $(SCRIV_SOURCE)
github_releases: $(SCRIV_SOURCE) ## Update GitHub releases.
$(DOCBIN)/python -m scriv github-release --all
comment_on_fixes: $(SCRIV_SOURCE) ## Add a comment to issues that were fixed.
python ci/comment_on_fixes.py $(REPO_OWNER)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/NOTICE.txt 0000644 0001751 0001751 00000001251 15073731535 014573 0 ustar 00runner runner Copyright 2001 Gareth Rees. All rights reserved.
Copyright 2004-2025 Ned Batchelder. All rights reserved.
Except where noted otherwise, this software is licensed under the Apache
License, Version 2.0 (the "License"); you may not use this work except in
compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9881895
coverage-7.11.0/PKG-INFO 0000644 0001751 0001751 00000021376 15073731560 014156 0 ustar 00runner runner Metadata-Version: 2.4
Name: coverage
Version: 7.11.0
Summary: Code coverage measurement for Python
Home-page: https://github.com/nedbat/coveragepy
Author: Ned Batchelder and 243 others
Author-email: ned@nedbatchelder.com
License: Apache-2.0
Project-URL: Documentation, https://coverage.readthedocs.io/en/7.11.0
Project-URL: Funding, https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=pypi
Project-URL: Issues, https://github.com/nedbat/coveragepy/issues
Project-URL: Mastodon, https://hachyderm.io/@coveragepy
Project-URL: Mastodon (nedbat), https://hachyderm.io/@nedbat
Keywords: code coverage testing
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Provides-Extra: toml
Requires-Dist: tomli; python_full_version <= "3.11.0a6" and extra == "toml"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary
.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
===========
Coverage.py
===========
Code coverage measurement for Python.
.. image:: https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg
:target: https://vshymanskyy.github.io/StandWithUkraine
:alt: Stand with Ukraine
-------------
| |kit| |license| |versions|
| |test-status| |quality-status| |docs| |metacov|
| |tidelift| |sponsor| |stars| |mastodon-coveragepy| |mastodon-nedbat|
|bluesky-nedbat|
Coverage.py measures code coverage, typically during test execution. It uses
the code analysis tools and tracing hooks provided in the Python standard
library to determine which lines are executable, and which have been executed.
Coverage.py runs on these versions of Python:
.. PYVERSIONS
* Python 3.10 through 3.15 alpha, including free-threading.
* PyPy3 versions 3.10 and 3.11.
Documentation is on `Read the Docs`_. Code repository and issue tracker are on
`GitHub`_.
.. _Read the Docs: https://coverage.readthedocs.io/en/7.11.0/
.. _GitHub: https://github.com/nedbat/coveragepy
**New in 7.x:**
``[run] patch`` setting;
``--save-signal`` option;
``[run] core`` setting;
``[run] source_dirs`` setting;
``Coverage.branch_stats()``;
multi-line exclusion patterns;
function/class reporting;
experimental support for sys.monitoring;
dropped support for Python up to 3.9;
added ``Coverage.collect()`` context manager;
improved data combining;
``[run] exclude_also`` setting;
``report --format=``;
type annotations.
**New in 6.x:**
dropped support for Python 2.7, 3.5, and 3.6;
write data on SIGTERM;
added support for 3.10 match/case statements.
For Enterprise
--------------
.. |tideliftlogo| image:: https://nedbatchelder.com/pix/Tidelift_Logo_small.png
:alt: Tidelift
:target: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=readme
.. list-table::
:widths: 10 100
* - |tideliftlogo|
- `Available as part of the Tidelift Subscription. `_
Coverage and thousands of other packages are working with
Tidelift to deliver one enterprise subscription that covers all of the open
source you use. If you want the flexibility of open source and the confidence
of commercial-grade software, this is for you.
`Learn more. `_
Getting Started
---------------
Looking to run ``coverage`` on your test suite? See the `Quick Start section`_
of the docs.
.. _Quick Start section: https://coverage.readthedocs.io/en/7.11.0/#quick-start
Change history
--------------
The complete history of changes is on the `change history page`_.
.. _change history page: https://coverage.readthedocs.io/en/7.11.0/changes.html
Code of Conduct
---------------
Everyone participating in the coverage.py project is expected to treat other
people with respect and to follow the guidelines articulated in the `Python
Community Code of Conduct`_.
.. _Python Community Code of Conduct: https://www.python.org/psf/codeofconduct/
Contributing
------------
Found a bug? Want to help improve the code or documentation? See the
`Contributing section`_ of the docs.
.. _Contributing section: https://coverage.readthedocs.io/en/7.11.0/contributing.html
Security
--------
To report a security vulnerability, please use the `Tidelift security
contact`_. Tidelift will coordinate the fix and disclosure.
.. _Tidelift security contact: https://tidelift.com/security
License
-------
Licensed under the `Apache 2.0 License`_. For details, see `NOTICE.txt`_.
.. _Apache 2.0 License: http://www.apache.org/licenses/LICENSE-2.0
.. _NOTICE.txt: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. |test-status| image:: https://github.com/nedbat/coveragepy/actions/workflows/testsuite.yml/badge.svg?branch=master&event=push
:target: https://github.com/nedbat/coveragepy/actions/workflows/testsuite.yml
:alt: Test suite status
.. |quality-status| image:: https://github.com/nedbat/coveragepy/actions/workflows/quality.yml/badge.svg?branch=master&event=push
:target: https://github.com/nedbat/coveragepy/actions/workflows/quality.yml
:alt: Quality check status
.. |docs| image:: https://readthedocs.org/projects/coverage/badge/?version=latest&style=flat
:target: https://coverage.readthedocs.io/en/7.11.0/
:alt: Documentation
.. |kit| image:: https://img.shields.io/pypi/v/coverage
:target: https://pypi.org/project/coverage/
:alt: PyPI status
.. |versions| image:: https://img.shields.io/pypi/pyversions/coverage.svg?logo=python&logoColor=FBE072
:target: https://pypi.org/project/coverage/
:alt: Python versions supported
.. |license| image:: https://img.shields.io/pypi/l/coverage.svg
:target: https://github.com/nedbat/coveragepy/blob/master/LICENSE.txt
:alt: License
.. |metacov| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/nedbat/8c6980f77988a327348f9b02bbaf67f5/raw/metacov.json
:target: https://nedbat.github.io/coverage-reports/latest.html
:alt: Coverage reports
.. |tidelift| image:: https://tidelift.com/badges/package/pypi/coverage
:target: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=readme
:alt: Tidelift
.. |stars| image:: https://img.shields.io/github/stars/nedbat/coveragepy.svg?logo=github&style=flat
:target: https://github.com/nedbat/coveragepy/stargazers
:alt: GitHub stars
.. |mastodon-nedbat| image:: https://img.shields.io/badge/dynamic/json?style=flat&labelColor=450657&logo=mastodon&logoColor=ffffff&label=@nedbat&query=followers_count&url=https%3A%2F%2Fhachyderm.io%2Fapi%2Fv1%2Faccounts%2Flookup%3Facct=nedbat
:target: https://hachyderm.io/@nedbat
:alt: nedbat on Mastodon
.. |mastodon-coveragepy| image:: https://img.shields.io/badge/dynamic/json?style=flat&labelColor=450657&logo=mastodon&logoColor=ffffff&label=@coveragepy&query=followers_count&url=https%3A%2F%2Fhachyderm.io%2Fapi%2Fv1%2Faccounts%2Flookup%3Facct=coveragepy
:target: https://hachyderm.io/@coveragepy
:alt: coveragepy on Mastodon
.. |bluesky-nedbat| image:: https://img.shields.io/badge/dynamic/json?style=flat&color=96a3b0&labelColor=3686f7&logo=icloud&logoColor=white&label=@nedbat&url=https%3A%2F%2Fpublic.api.bsky.app%2Fxrpc%2Fapp.bsky.actor.getProfile%3Factor=nedbat.com&query=followersCount
:target: https://bsky.app/profile/nedbat.com
:alt: nedbat on Bluesky
.. |sponsor| image:: https://img.shields.io/badge/%E2%9D%A4-Sponsor%20me-brightgreen?style=flat&logo=GitHub
:target: https://github.com/sponsors/nedbat
:alt: Sponsor me on GitHub
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/README.rst 0000644 0001751 0001751 00000015471 15073731535 014551 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
===========
Coverage.py
===========
Code coverage measurement for Python.
.. image:: https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg
:target: https://vshymanskyy.github.io/StandWithUkraine
:alt: Stand with Ukraine
-------------
| |kit| |license| |versions|
| |test-status| |quality-status| |docs| |metacov|
| |tidelift| |sponsor| |stars| |mastodon-coveragepy| |mastodon-nedbat|
|bluesky-nedbat|
Coverage.py measures code coverage, typically during test execution. It uses
the code analysis tools and tracing hooks provided in the Python standard
library to determine which lines are executable, and which have been executed.
Coverage.py runs on these versions of Python:
.. PYVERSIONS
* Python 3.10 through 3.15 alpha, including free-threading.
* PyPy3 versions 3.10 and 3.11.
Documentation is on `Read the Docs`_. Code repository and issue tracker are on
`GitHub`_.
.. _Read the Docs: https://coverage.readthedocs.io/
.. _GitHub: https://github.com/nedbat/coveragepy
**New in 7.x:**
``[run] patch`` setting;
``--save-signal`` option;
``[run] core`` setting;
``[run] source_dirs`` setting;
``Coverage.branch_stats()``;
multi-line exclusion patterns;
function/class reporting;
experimental support for sys.monitoring;
dropped support for Python up to 3.9;
added ``Coverage.collect()`` context manager;
improved data combining;
``[run] exclude_also`` setting;
``report --format=``;
type annotations.
**New in 6.x:**
dropped support for Python 2.7, 3.5, and 3.6;
write data on SIGTERM;
added support for 3.10 match/case statements.
For Enterprise
--------------
.. |tideliftlogo| image:: https://nedbatchelder.com/pix/Tidelift_Logo_small.png
:alt: Tidelift
:target: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=readme
.. list-table::
:widths: 10 100
* - |tideliftlogo|
- `Available as part of the Tidelift Subscription. `_
Coverage and thousands of other packages are working with
Tidelift to deliver one enterprise subscription that covers all of the open
source you use. If you want the flexibility of open source and the confidence
of commercial-grade software, this is for you.
`Learn more. `_
Getting Started
---------------
Looking to run ``coverage`` on your test suite? See the `Quick Start section`_
of the docs.
.. _Quick Start section: https://coverage.readthedocs.io/#quick-start
Change history
--------------
The complete history of changes is on the `change history page`_.
.. _change history page: https://coverage.readthedocs.io/en/latest/changes.html
Code of Conduct
---------------
Everyone participating in the coverage.py project is expected to treat other
people with respect and to follow the guidelines articulated in the `Python
Community Code of Conduct`_.
.. _Python Community Code of Conduct: https://www.python.org/psf/codeofconduct/
Contributing
------------
Found a bug? Want to help improve the code or documentation? See the
`Contributing section`_ of the docs.
.. _Contributing section: https://coverage.readthedocs.io/en/latest/contributing.html
Security
--------
To report a security vulnerability, please use the `Tidelift security
contact`_. Tidelift will coordinate the fix and disclosure.
.. _Tidelift security contact: https://tidelift.com/security
License
-------
Licensed under the `Apache 2.0 License`_. For details, see `NOTICE.txt`_.
.. _Apache 2.0 License: http://www.apache.org/licenses/LICENSE-2.0
.. _NOTICE.txt: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. |test-status| image:: https://github.com/nedbat/coveragepy/actions/workflows/testsuite.yml/badge.svg?branch=master&event=push
:target: https://github.com/nedbat/coveragepy/actions/workflows/testsuite.yml
:alt: Test suite status
.. |quality-status| image:: https://github.com/nedbat/coveragepy/actions/workflows/quality.yml/badge.svg?branch=master&event=push
:target: https://github.com/nedbat/coveragepy/actions/workflows/quality.yml
:alt: Quality check status
.. |docs| image:: https://readthedocs.org/projects/coverage/badge/?version=latest&style=flat
:target: https://coverage.readthedocs.io/
:alt: Documentation
.. |kit| image:: https://img.shields.io/pypi/v/coverage
:target: https://pypi.org/project/coverage/
:alt: PyPI status
.. |versions| image:: https://img.shields.io/pypi/pyversions/coverage.svg?logo=python&logoColor=FBE072
:target: https://pypi.org/project/coverage/
:alt: Python versions supported
.. |license| image:: https://img.shields.io/pypi/l/coverage.svg
:target: https://github.com/nedbat/coveragepy/blob/master/LICENSE.txt
:alt: License
.. |metacov| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/nedbat/8c6980f77988a327348f9b02bbaf67f5/raw/metacov.json
:target: https://nedbat.github.io/coverage-reports/latest.html
:alt: Coverage reports
.. |tidelift| image:: https://tidelift.com/badges/package/pypi/coverage
:target: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=readme
:alt: Tidelift
.. |stars| image:: https://img.shields.io/github/stars/nedbat/coveragepy.svg?logo=github&style=flat
:target: https://github.com/nedbat/coveragepy/stargazers
:alt: GitHub stars
.. |mastodon-nedbat| image:: https://img.shields.io/badge/dynamic/json?style=flat&labelColor=450657&logo=mastodon&logoColor=ffffff&label=@nedbat&query=followers_count&url=https%3A%2F%2Fhachyderm.io%2Fapi%2Fv1%2Faccounts%2Flookup%3Facct=nedbat
:target: https://hachyderm.io/@nedbat
:alt: nedbat on Mastodon
.. |mastodon-coveragepy| image:: https://img.shields.io/badge/dynamic/json?style=flat&labelColor=450657&logo=mastodon&logoColor=ffffff&label=@coveragepy&query=followers_count&url=https%3A%2F%2Fhachyderm.io%2Fapi%2Fv1%2Faccounts%2Flookup%3Facct=coveragepy
:target: https://hachyderm.io/@coveragepy
:alt: coveragepy on Mastodon
.. |bluesky-nedbat| image:: https://img.shields.io/badge/dynamic/json?style=flat&color=96a3b0&labelColor=3686f7&logo=icloud&logoColor=white&label=@nedbat&url=https%3A%2F%2Fpublic.api.bsky.app%2Fxrpc%2Fapp.bsky.actor.getProfile%3Factor=nedbat.com&query=followersCount
:target: https://bsky.app/profile/nedbat.com
:alt: nedbat on Bluesky
.. |sponsor| image:: https://img.shields.io/badge/%E2%9D%A4-Sponsor%20me-brightgreen?style=flat&logo=GitHub
:target: https://github.com/sponsors/nedbat
:alt: Sponsor me on GitHub
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/__main__.py 0000644 0001751 0001751 00000000645 15073731535 015151 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Be able to execute coverage.py by pointing Python at a working tree."""
import runpy
import os
PKG = "coverage"
run_globals = runpy.run_module(PKG, run_name="__main__", alter_sys=True)
executed = os.path.splitext(os.path.basename(run_globals["__file__"]))[0]
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9311895
coverage-7.11.0/ci/ 0000755 0001751 0001751 00000000000 15073731560 013443 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/ci/README.txt 0000644 0001751 0001751 00000000061 15073731535 015140 0 ustar 00runner runner Files to support continuous integration systems.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/ci/comment_on_fixes.py 0000644 0001751 0001751 00000003722 15073731535 017357 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Add a release comment to all the issues mentioned in the latest release."""
import re
import sys
from scriv.scriv import Scriv
from session import get_session
scriv = Scriv()
changelog = scriv.changelog()
changelog.read()
# Get the first entry in the changelog:
for etitle, sections in changelog.entries().items():
version = etitle.split()[1] # particular to our title format.
text = "\n".join(sections)
break
comment = (
f"This is now released as part of [coverage {version}]"
+ f"(https://pypi.org/project/coverage/{version})."
)
print(f"Comment will be:\n\n{comment}\n")
repo_owner = sys.argv[1]
url_matches = re.finditer(rf"https://github.com/{repo_owner}/(issues|pull)/(\d+)", text)
urls = set((m[0], m[1], m[2]) for m in url_matches)
for url, kind, number in urls:
do_comment = False
if kind == "issues":
url = f"https://api.github.com/repos/{repo_owner}/issues/{number}"
issue_data = get_session().get(url).json()
html_url = issue_data["html_url"]
if issue_data["state"] == "closed":
do_comment = True
else:
print(f"Still open, comment manually: {url}")
else:
url = f"https://api.github.com/repos/{repo_owner}/pulls/{number}"
pull_data = get_session().get(url).json()
html_url = pull_data["html_url"]
if pull_data["state"] == "closed":
if pull_data["merged"]:
do_comment = True
else:
print(f"Not merged, comment manually: {html_url}")
else:
print(f"Still open, comment manually: {html_url}")
if do_comment:
print(f"Commenting on {html_url}")
url = f"https://api.github.com/repos/{repo_owner}/issues/{number}/comments"
resp = get_session().post(url, json={"body": comment})
print(resp)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/ci/session.py 0000644 0001751 0001751 00000001635 15073731535 015507 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Help make a requests Session with proper authentication."""
import os
import sys
import requests
_SESSIONS = {}
def get_session(env="GITHUB_TOKEN"):
"""Get a properly authenticated requests Session.
Get the token from the `env` environment variable.
"""
session = _SESSIONS.get(env)
if session is None:
token = os.environ.get(env)
if token is None:
sys.exit(f"!! Must have {env}")
session = requests.session()
session.headers["Authorization"] = f"token {token}"
# requests.get() will always prefer the .netrc file even if a header
# is already set. This tells it to ignore the .netrc file.
session.trust_env = False
_SESSIONS[env] = session
return session
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/ci/trigger_action.py 0000644 0001751 0001751 00000003016 15073731535 017017 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Trigger a repository_dispatch GitHub action."""
import sys
import time
from session import get_session
# The GitHub URL makes no mention of which workflow to use. It's found based on
# the event_type, which matches the types in the workflow:
#
# on:
# repository_dispatch:
# types:
# - build-kits
#
def latest_action_run(repo_owner, event):
"""
Get the newest action run for a certain kind of event.
"""
resp = get_session().get(
f"https://api.github.com/repos/{repo_owner}/actions/runs?event={event}"
)
resp.raise_for_status()
return resp.json()["workflow_runs"][0]
def dispatch_action(repo_owner, event_type):
"""
Trigger an action with a particular dispatch event_type.
Wait until it starts, and print the URL to it.
"""
latest_id = latest_action_run(repo_owner, "repository_dispatch")["id"]
url = f"https://api.github.com/repos/{repo_owner}/dispatches"
data = {"event_type": event_type}
resp = get_session().post(url, json=data)
resp.raise_for_status()
print(f"Success: {resp.status_code}")
while True:
run = latest_action_run(repo_owner, "repository_dispatch")
if run["id"] != latest_id:
break
print(".", end=" ", flush=True)
time.sleep(0.5)
print(run["html_url"])
if __name__ == "__main__":
dispatch_action(*sys.argv[1:])
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/ci/update_rtfd.py 0000644 0001751 0001751 00000005672 15073731535 016332 0 ustar 00runner runner """
Update ReadTheDocs to show and hide releases.
"""
import re
import sys
from session import get_session
# How many from each level to show.
NUM_MAJORS = 3
NUM_MINORS = 3
OLD_MINORS = 1
NUM_MICROS = 1
OLD_MICROS = 1
def get_all_versions(project):
"""Pull all the versions for a project from ReadTheDocs."""
versions = []
session = get_session("RTFD_TOKEN")
url = f"https://readthedocs.org/api/v3/projects/{project}/versions/"
while url:
resp = session.get(url)
resp.raise_for_status()
data = resp.json()
versions.extend(data["results"])
url = data["next"]
return versions
def version_tuple(vstr):
"""Convert a tag name into a version_info tuple."""
m = re.fullmatch(r"[^\d]*(\d+)\.(\d+)(?:\.(\d+))?(?:([abc])(\d+))?", vstr)
if not m:
return None
return (
int(m[1]),
int(m[2]),
int(m[3] or 0),
(m[4] or "final"),
int(m[5] or 0),
)
def main(project):
"""Update ReadTheDocs for the versions we want to show."""
# Get all the tags. Where there are dupes, keep the shorter tag for a version.
versions = get_all_versions(project)
versions.sort(key=(lambda v: len(v["verbose_name"])), reverse=True)
vdict = {}
for v in versions:
if v["type"] == "tag":
vinfo = version_tuple(v["verbose_name"])
if vinfo and vinfo[3] == "final":
vdict[vinfo] = v
# Decide which to show and update them.
majors = set()
minors = set()
micros = set()
minors_to_show = NUM_MINORS
micros_to_show = NUM_MICROS
session = get_session("RTFD_TOKEN")
version_list = sorted(vdict.items(), reverse=True)
for vi, ver in version_list:
if vi[:1] not in majors:
majors.add(vi[:1])
minors = set()
if len(majors) > 1:
minors_to_show = OLD_MINORS
micros_to_show = OLD_MICROS
if vi[:2] not in minors:
minors.add(vi[:2])
micros = set()
if vi[:3] not in micros:
micros.add(vi[:3])
show_it = (
len(majors) <= NUM_MAJORS
and len(minors) <= minors_to_show
and len(micros) <= micros_to_show
)
active = ver["active"] or (len(majors) <= NUM_MAJORS)
hidden = not show_it
update = ver["active"] != active or ver["hidden"] != hidden
if update:
print(f"Updating {ver['verbose_name']} to {active=}, {hidden=}")
url = ver["_links"]["_self"]
resp = session.patch(url, data={"active": active, "hidden": hidden})
resp.raise_for_status()
# Set the default version.
latest = version_list[0][1]
print(f"Setting default version to {latest['slug']}")
url = latest["_links"]["project"]
resp = session.patch(url, data={"default_version": latest["slug"]})
resp.raise_for_status()
if __name__ == "__main__":
main(sys.argv[1])
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9391894
coverage-7.11.0/coverage/ 0000755 0001751 0001751 00000000000 15073731560 014643 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/__init__.py 0000644 0001751 0001751 00000002047 15073731535 016761 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""
Code coverage measurement for Python.
Ned Batchelder
https://coverage.readthedocs.io
"""
from __future__ import annotations
# isort: skip_file
# mypy's convention is that "import as" names are public from the module.
# We import names as themselves to indicate that. Pylint sees it as pointless,
# so disable its warning.
# pylint: disable=useless-import-alias
from coverage.version import (
__version__ as __version__,
version_info as version_info,
)
from coverage.control import (
Coverage as Coverage,
process_startup as process_startup,
)
from coverage.data import CoverageData as CoverageData
from coverage.exceptions import CoverageException as CoverageException
from coverage.plugin import (
CodeRegion as CodeRegion,
CoveragePlugin as CoveragePlugin,
FileReporter as FileReporter,
FileTracer as FileTracer,
)
# Backward compatibility.
coverage = Coverage
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/__main__.py 0000644 0001751 0001751 00000000447 15073731535 016744 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Coverage.py's main entry point."""
from __future__ import annotations
import sys
from coverage.cmdline import main
sys.exit(main())
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/annotate.py 0000644 0001751 0001751 00000007245 15073731535 017040 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Source file annotation for coverage.py."""
from __future__ import annotations
import os
import re
from collections.abc import Iterable
from typing import TYPE_CHECKING
from coverage.files import flat_rootname
from coverage.misc import ensure_dir, isolate_module
from coverage.plugin import FileReporter
from coverage.report_core import get_analysis_to_report
from coverage.results import Analysis
from coverage.types import TMorf
if TYPE_CHECKING:
from coverage import Coverage
os = isolate_module(os)
class AnnotateReporter:
"""Generate annotated source files showing line coverage.
This reporter creates annotated copies of the measured source files. Each
.py file is copied as a .py,cover file, with a left-hand margin annotating
each line::
> def h(x):
- if 0: #pragma: no cover
- pass
> if x == 1:
! a = 1
> else:
> a = 2
> h(2)
Executed lines use ">", lines not executed use "!", lines excluded from
consideration use "-".
"""
def __init__(self, coverage: Coverage) -> None:
self.coverage = coverage
self.config = self.coverage.config
self.directory: str | None = None
blank_re = re.compile(r"\s*(#|$)")
else_re = re.compile(r"\s*else\s*:\s*(#|$)")
def report(self, morfs: Iterable[TMorf] | None, directory: str | None = None) -> None:
"""Run the report.
See `coverage.report()` for arguments.
"""
self.directory = directory
self.coverage.get_data()
for fr, analysis in get_analysis_to_report(self.coverage, morfs):
self.annotate_file(fr, analysis)
def annotate_file(self, fr: FileReporter, analysis: Analysis) -> None:
"""Annotate a single file.
`fr` is the FileReporter for the file to annotate.
"""
statements = sorted(analysis.statements)
missing = sorted(analysis.missing)
excluded = sorted(analysis.excluded)
if self.directory:
ensure_dir(self.directory)
dest_file = os.path.join(self.directory, flat_rootname(fr.relative_filename()))
assert dest_file.endswith("_py")
dest_file = dest_file[:-3] + ".py"
else:
dest_file = fr.filename
dest_file += ",cover"
with open(dest_file, "w", encoding="utf-8") as dest:
i = j = 0
covered = True
source = fr.source()
for lineno, line in enumerate(source.splitlines(True), start=1):
while i < len(statements) and statements[i] < lineno:
i += 1
while j < len(missing) and missing[j] < lineno:
j += 1
if i < len(statements) and statements[i] == lineno:
covered = j >= len(missing) or missing[j] > lineno
if self.blank_re.match(line):
dest.write(" ")
elif self.else_re.match(line):
# Special logic for lines containing only "else:".
if j >= len(missing):
dest.write("> ")
elif statements[i] == missing[j]:
dest.write("! ")
else:
dest.write("> ")
elif lineno in excluded:
dest.write("- ")
elif covered:
dest.write("> ")
else:
dest.write("! ")
dest.write(line)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/bytecode.py 0000644 0001751 0001751 00000014257 15073731535 017026 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Bytecode analysis for coverage.py"""
from __future__ import annotations
import collections
import dis
from collections.abc import Iterator
from types import CodeType
from typing import Iterable, Optional
from coverage.types import TArc, TOffset
def code_objects(code: CodeType) -> Iterator[CodeType]:
"""Iterate over all the code objects in `code`."""
stack = [code]
while stack:
# We're going to return the code object on the stack, but first
# push its children for later returning.
code = stack.pop()
for c in code.co_consts:
if isinstance(c, CodeType):
stack.append(c)
yield code
def op_set(*op_names: str) -> set[int]:
"""Make a set of opcodes from instruction names.
The names might not exist in this version of Python, skip those if not.
"""
return {op for name in op_names if (op := dis.opmap.get(name))}
# Opcodes that are unconditional jumps elsewhere.
ALWAYS_JUMPS = op_set(
"JUMP_BACKWARD",
"JUMP_BACKWARD_NO_INTERRUPT",
"JUMP_FORWARD",
)
# Opcodes that exit from a function.
RETURNS = op_set(
"RETURN_VALUE",
"RETURN_GENERATOR",
)
# Opcodes that do nothing.
NOPS = op_set(
"NOP",
"NOT_TAKEN",
)
class InstructionWalker:
"""Utility to step through trails of instructions.
We have two reasons to need sequences of instructions from a code object:
First, in strict sequence to visit all the instructions in the object.
This is `walk(follow_jumps=False)`. Second, we want to follow jumps to
understand how execution will flow: `walk(follow_jumps=True)`.
"""
def __init__(self, code: CodeType) -> None:
self.code = code
self.insts: dict[TOffset, dis.Instruction] = {}
inst = None
for inst in dis.get_instructions(code):
self.insts[inst.offset] = inst
assert inst is not None
self.max_offset = inst.offset
def walk(
self, *, start_at: TOffset = 0, follow_jumps: bool = True
) -> Iterable[dis.Instruction]:
"""
Yield instructions starting from `start_at`. Follow unconditional
jumps if `follow_jumps` is true.
"""
seen = set()
offset = start_at
while offset < self.max_offset + 1:
if offset in seen:
break
seen.add(offset)
if inst := self.insts.get(offset):
yield inst
if follow_jumps and inst.opcode in ALWAYS_JUMPS:
offset = inst.jump_target
continue
offset += 2
TBranchTrailsOneSource = dict[Optional[TArc], set[TOffset]]
TBranchTrails = dict[TOffset, TBranchTrailsOneSource]
def branch_trails(code: CodeType) -> TBranchTrails:
"""
Calculate branch trails for `code`.
Instructions can have a jump_target, where they might jump to next. Some
instructions with a jump_target are unconditional jumps (ALWAYS_JUMPS), so
they aren't interesting to us, since they aren't the start of a branch
possibility.
Instructions that might or might not jump somewhere else are branch
possibilities. For each of those, we track a trail of instructions. These
are lists of instruction offsets, the next instructions that can execute.
We follow the trail until we get to a new source line. That gives us the
arc from the original instruction's line to the new source line.
"""
the_trails: TBranchTrails = collections.defaultdict(lambda: collections.defaultdict(set))
iwalker = InstructionWalker(code)
for inst in iwalker.walk(follow_jumps=False):
if not inst.jump_target:
# We only care about instructions with jump targets.
continue
if inst.opcode in ALWAYS_JUMPS:
# We don't care about unconditional jumps.
continue
from_line = inst.line_number
if from_line is None:
continue
def add_one_branch_trail(
trails: TBranchTrailsOneSource,
start_at: TOffset,
) -> None:
# pylint: disable=cell-var-from-loop
inst_offsets: set[TOffset] = set()
to_line = None
for inst2 in iwalker.walk(start_at=start_at, follow_jumps=True):
inst_offsets.add(inst2.offset)
if inst2.line_number and inst2.line_number != from_line:
to_line = inst2.line_number
break
elif inst2.jump_target and (inst2.opcode not in ALWAYS_JUMPS):
break
elif inst2.opcode in RETURNS:
to_line = -code.co_firstlineno
break
if to_line is not None:
trails[(from_line, to_line)].update(inst_offsets)
else:
trails[None] = set()
# Calculate two trails: one from the next instruction, and one from the
# jump_target instruction.
trails: TBranchTrailsOneSource = collections.defaultdict(set)
add_one_branch_trail(trails, start_at=inst.offset + 2)
add_one_branch_trail(trails, start_at=inst.jump_target)
the_trails[inst.offset] = trails
# Sometimes we get BRANCH_RIGHT or BRANCH_LEFT events from instructions
# other than the original jump possibility instruction. Register each
# trail under all of their offsets so we can pick up in the middle of a
# trail if need be.
for arc, offsets in trails.items():
for offset in offsets:
the_trails[offset][arc].update(offsets)
return the_trails
def always_jumps(code: CodeType) -> dict[TOffset, TOffset]:
"""Make a map of unconditional bytecodes jumping to others.
Only include bytecodes that do no work and go to another bytecode.
"""
jumps = {}
iwalker = InstructionWalker(code)
for inst in iwalker.walk(follow_jumps=False):
if inst.opcode in ALWAYS_JUMPS:
jumps[inst.offset] = inst.jump_target
elif inst.opcode in NOPS:
jumps[inst.offset] = inst.offset + 2
return jumps
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/cmdline.py 0000644 0001751 0001751 00000107336 15073731535 016644 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Command-line support for coverage.py."""
from __future__ import annotations
import glob
import optparse
import os
import os.path
import shlex
import signal
import sys
import textwrap
import traceback
import types
from typing import Any, NoReturn, cast
import coverage
from coverage import Coverage, env
from coverage.config import CoverageConfig
from coverage.control import DEFAULT_DATAFILE
from coverage.core import CTRACER_FILE
from coverage.data import combinable_files, debug_data_file
from coverage.debug import info_header, short_stack, write_formatted_info
from coverage.exceptions import NoSource, CoverageException, _ExceptionDuringRun
from coverage.execfile import PyRunner
from coverage.results import display_covered, should_fail_under
from coverage.version import __url__
# When adding to this file, alphabetization is important. Look for
# "alphabetize" comments throughout.
def oneline(text: str) -> str:
"""Turn a multi-line string into one line for help to reformat nicely."""
return " ".join(text.split())
class Opts:
"""A namespace class for individual options we'll build parsers from."""
# Keep these entries alphabetized (roughly) by the option name as it
# appears on the command line.
append = optparse.make_option(
"-a",
"--append",
action="store_true",
help="Append data to the data file. Otherwise it starts clean each time.",
)
branch = optparse.make_option(
"",
"--branch",
action="store_true",
help="Measure branch coverage in addition to statement coverage.",
)
concurrency = optparse.make_option(
"",
"--concurrency",
action="store",
metavar="LIBS",
help=oneline(
"""
Properly measure code using a concurrency library.
Valid values are: {}, or a comma-list of them.
"""
).format(", ".join(sorted(CoverageConfig.CONCURRENCY_CHOICES))),
)
context = optparse.make_option(
"",
"--context",
action="store",
metavar="LABEL",
help="The context label to record for this coverage run.",
)
contexts = optparse.make_option(
"",
"--contexts",
action="store",
metavar="REGEX1,REGEX2,...",
help=oneline(
"""
Only display data from lines covered in the given contexts.
Accepts Python regexes, which must be quoted.
"""
),
)
datafile = optparse.make_option(
"",
"--data-file",
action="store",
metavar="DATAFILE",
help=oneline(
"""
Base name of the data files to operate on.
Defaults to '.coverage'. [env: COVERAGE_FILE]
"""
),
)
datafle_input = optparse.make_option(
"",
"--data-file",
action="store",
metavar="INFILE",
help=oneline(
"""
Read coverage data for report generation from this file.
Defaults to '.coverage'. [env: COVERAGE_FILE]
"""
),
)
datafile_output = optparse.make_option(
"",
"--data-file",
action="store",
metavar="OUTFILE",
help=oneline(
"""
Write the recorded coverage data to this file.
Defaults to '.coverage'. [env: COVERAGE_FILE]
"""
),
)
debug = optparse.make_option(
"",
"--debug",
action="store",
metavar="OPTS",
help="Debug options, separated by commas. [env: COVERAGE_DEBUG]",
)
directory = optparse.make_option(
"-d",
"--directory",
action="store",
metavar="DIR",
help="Write the output files to DIR.",
)
fail_under = optparse.make_option(
"",
"--fail-under",
action="store",
metavar="MIN",
type="float",
help="Exit with a status of 2 if the total coverage is less than MIN.",
)
format = optparse.make_option(
"",
"--format",
action="store",
metavar="FORMAT",
help="Output format, either text (default), markdown, or total.",
)
help = optparse.make_option(
"-h",
"--help",
action="store_true",
help="Get help on this command.",
)
ignore_errors = optparse.make_option(
"-i",
"--ignore-errors",
action="store_true",
help="Ignore errors while reading source files.",
)
include = optparse.make_option(
"",
"--include",
action="store",
metavar="PAT1,PAT2,...",
help=oneline(
"""
Include only files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
"""
),
)
keep = optparse.make_option(
"",
"--keep",
action="store_true",
help="Keep original coverage files, otherwise they are deleted.",
)
pylib = optparse.make_option(
"-L",
"--pylib",
action="store_true",
help=oneline(
"""
Measure coverage even inside the Python installed library,
which isn't done by default.
"""
),
)
show_missing = optparse.make_option(
"-m",
"--show-missing",
action="store_true",
help="Show line numbers of statements in each module that weren't executed.",
)
module = optparse.make_option(
"-m",
"--module",
action="store_true",
help=oneline(
"""
is an importable Python module, not a script path,
to be run as 'python -m' would run it.
"""
),
)
omit = optparse.make_option(
"",
"--omit",
action="store",
metavar="PAT1,PAT2,...",
help=oneline(
"""
Omit files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
"""
),
)
output_xml = optparse.make_option(
"-o",
"",
action="store",
dest="outfile",
metavar="OUTFILE",
help="Write the XML report to this file. Defaults to 'coverage.xml'",
)
output_json = optparse.make_option(
"-o",
"",
action="store",
dest="outfile",
metavar="OUTFILE",
help="Write the JSON report to this file. Defaults to 'coverage.json'",
)
output_lcov = optparse.make_option(
"-o",
"",
action="store",
dest="outfile",
metavar="OUTFILE",
help="Write the LCOV report to this file. Defaults to 'coverage.lcov'",
)
json_pretty_print = optparse.make_option(
"",
"--pretty-print",
action="store_true",
help="Format the JSON for human readers.",
)
parallel_mode = optparse.make_option(
"-p",
"--parallel-mode",
action="store_true",
help=oneline(
"""
Append a unique suffix to the data file name to collect separate
data from multiple processes.
"""
),
)
precision = optparse.make_option(
"",
"--precision",
action="store",
metavar="N",
type=int,
help=oneline(
"""
Number of digits after the decimal point to display for
reported coverage percentages.
"""
),
)
quiet = optparse.make_option(
"-q",
"--quiet",
action="store_true",
help="Don't print messages about what is happening.",
)
rcfile = optparse.make_option(
"",
"--rcfile",
action="store",
help=oneline(
"""
Specify configuration file.
By default '.coveragerc', 'setup.cfg', 'tox.ini', and
'pyproject.toml' are tried. [env: COVERAGE_RCFILE]
"""
),
)
save_signal = optparse.make_option(
"",
"--save-signal",
action="store",
metavar="SIGNAL",
choices=["USR1", "USR2"],
help=oneline(
"""
Specify a signal that will trigger coverage to write its collected data.
Supported values are: USR1, USR2. Not available on Windows.
"""
),
)
show_contexts = optparse.make_option(
"--show-contexts",
action="store_true",
help="Show contexts for covered lines.",
)
skip_covered = optparse.make_option(
"--skip-covered",
action="store_true",
help="Skip files with 100% coverage.",
)
no_skip_covered = optparse.make_option(
"--no-skip-covered",
action="store_false",
dest="skip_covered",
help="Disable --skip-covered.",
)
skip_empty = optparse.make_option(
"--skip-empty",
action="store_true",
help="Skip files with no code.",
)
sort = optparse.make_option(
"--sort",
action="store",
metavar="COLUMN",
help=oneline(
"""
Sort the report by the named column: name, stmts, miss, branch, brpart, or cover.
Default is name.
"""
),
)
source = optparse.make_option(
"",
"--source",
action="store",
metavar="SRC1,SRC2,...",
help="A list of directories or importable names of code to measure.",
)
timid = optparse.make_option(
"",
"--timid",
action="store_true",
help="Use the slower Python trace function core.",
)
title = optparse.make_option(
"",
"--title",
action="store",
metavar="TITLE",
help="A text string to use as the title on the HTML.",
)
version = optparse.make_option(
"",
"--version",
action="store_true",
help="Display version information and exit.",
)
class CoverageOptionParser(optparse.OptionParser):
"""Base OptionParser for coverage.py.
Problems don't exit the program.
Defaults are initialized for all options.
"""
def __init__(self, *args: Any, **kwargs: Any) -> None:
kwargs["add_help_option"] = False
super().__init__(*args, **kwargs)
self.set_defaults(
# Keep these arguments alphabetized by their names.
action=None,
append=None,
branch=None,
concurrency=None,
context=None,
contexts=None,
data_file=None,
debug=None,
directory=None,
fail_under=None,
format=None,
help=None,
ignore_errors=None,
include=None,
keep=None,
module=None,
omit=None,
parallel_mode=None,
precision=None,
pylib=None,
quiet=None,
rcfile=True,
save_signal=None,
show_contexts=None,
show_missing=None,
skip_covered=None,
skip_empty=None,
sort=None,
source=None,
timid=None,
title=None,
version=None,
)
self.disable_interspersed_args()
class OptionParserError(Exception):
"""Used to stop the optparse error handler ending the process."""
pass
def parse_args_ok(self, args: list[str]) -> tuple[bool, optparse.Values | None, list[str]]:
"""Call optparse.parse_args, but return a triple:
(ok, options, args)
"""
try:
options, args = super().parse_args(args)
except self.OptionParserError:
return False, None, []
return True, options, args
def error(self, msg: str) -> NoReturn:
"""Override optparse.error so sys.exit doesn't get called."""
show_help(msg)
raise self.OptionParserError
class GlobalOptionParser(CoverageOptionParser):
"""Command-line parser for coverage.py global option arguments."""
def __init__(self) -> None:
super().__init__()
self.add_options(
[
Opts.help,
Opts.version,
]
)
class CmdOptionParser(CoverageOptionParser):
"""Parse one of the new-style commands for coverage.py."""
def __init__(
self,
action: str,
options: list[optparse.Option],
description: str,
usage: str | None = None,
):
"""Create an OptionParser for a coverage.py command.
`action` is the slug to put into `options.action`.
`options` is a list of Option's for the command.
`description` is the description of the command, for the help text.
`usage` is the usage string to display in help.
"""
if usage:
usage = "%prog " + usage
super().__init__(
usage=usage,
description=description,
)
self.set_defaults(action=action)
self.add_options(options)
self.cmd = action
def __eq__(self, other: str) -> bool: # type: ignore[override]
# A convenience equality, so that I can put strings in unit test
# results, and they will compare equal to objects.
return other == f""
__hash__ = None # type: ignore[assignment]
def get_prog_name(self) -> str:
"""Override of an undocumented function in optparse.OptionParser."""
program_name = super().get_prog_name()
# Include the sub-command for this parser as part of the command.
return f"{program_name} {self.cmd}"
# In lists of Opts, keep them alphabetized by the option names as they appear
# on the command line, since these lists determine the order of the options in
# the help output.
#
# In COMMANDS, keep the keys (command names) alphabetized.
GLOBAL_ARGS = [
Opts.debug,
Opts.help,
Opts.rcfile,
]
COMMANDS = {
"annotate": CmdOptionParser(
"annotate",
[
Opts.directory,
Opts.datafle_input,
Opts.ignore_errors,
Opts.include,
Opts.omit,
]
+ GLOBAL_ARGS,
usage="[options] [modules]",
description=oneline(
"""
Make annotated copies of the given files, marking statements that are executed
with > and statements that are missed with !.
"""
),
),
"combine": CmdOptionParser(
"combine",
[
Opts.append,
Opts.datafile,
Opts.keep,
Opts.quiet,
]
+ GLOBAL_ARGS,
usage="[options] ... ",
description=oneline(
"""
Combine data from multiple coverage files.
The combined results are written to a single
file representing the union of the data. The positional
arguments are data files or directories containing data files.
If no paths are provided, data files in the default data file's
directory are combined.
"""
),
),
"debug": CmdOptionParser(
"debug",
GLOBAL_ARGS,
usage="",
description=oneline(
"""
Display information about the internals of coverage.py,
for diagnosing problems.
Topics are:
'data' to show a summary of the collected data;
'sys' to show installation information;
'config' to show the configuration;
'premain' to show what is calling coverage;
'pybehave' to show internal flags describing Python behavior.
"""
),
),
"erase": CmdOptionParser(
"erase",
[
Opts.datafile,
]
+ GLOBAL_ARGS,
description="Erase previously collected coverage data.",
),
"help": CmdOptionParser(
"help",
GLOBAL_ARGS,
usage="[command]",
description="Describe how to use coverage.py",
),
"html": CmdOptionParser(
"html",
[
Opts.contexts,
Opts.directory,
Opts.datafle_input,
Opts.fail_under,
Opts.ignore_errors,
Opts.include,
Opts.omit,
Opts.precision,
Opts.quiet,
Opts.show_contexts,
Opts.skip_covered,
Opts.no_skip_covered,
Opts.skip_empty,
Opts.title,
]
+ GLOBAL_ARGS,
usage="[options] [modules]",
description=oneline(
"""
Create an HTML report of the coverage of the files.
Each file gets its own page, with the source decorated to show
executed, excluded, and missed lines.
"""
),
),
"json": CmdOptionParser(
"json",
[
Opts.contexts,
Opts.datafle_input,
Opts.fail_under,
Opts.ignore_errors,
Opts.include,
Opts.omit,
Opts.output_json,
Opts.json_pretty_print,
Opts.quiet,
Opts.show_contexts,
]
+ GLOBAL_ARGS,
usage="[options] [modules]",
description="Generate a JSON report of coverage results.",
),
"lcov": CmdOptionParser(
"lcov",
[
Opts.datafle_input,
Opts.fail_under,
Opts.ignore_errors,
Opts.include,
Opts.output_lcov,
Opts.omit,
Opts.quiet,
]
+ GLOBAL_ARGS,
usage="[options] [modules]",
description="Generate an LCOV report of coverage results.",
),
"report": CmdOptionParser(
"report",
[
Opts.contexts,
Opts.datafle_input,
Opts.fail_under,
Opts.format,
Opts.ignore_errors,
Opts.include,
Opts.omit,
Opts.precision,
Opts.sort,
Opts.show_missing,
Opts.skip_covered,
Opts.no_skip_covered,
Opts.skip_empty,
]
+ GLOBAL_ARGS,
usage="[options] [modules]",
description="Report coverage statistics on modules.",
),
"run": CmdOptionParser(
"run",
[
Opts.append,
Opts.branch,
Opts.concurrency,
Opts.context,
Opts.datafile_output,
Opts.include,
Opts.module,
Opts.omit,
Opts.pylib,
Opts.parallel_mode,
Opts.save_signal,
Opts.source,
Opts.timid,
]
+ GLOBAL_ARGS,
usage="[options] [program options]",
description="Run a Python program, measuring code execution.",
),
"xml": CmdOptionParser(
"xml",
[
Opts.datafle_input,
Opts.fail_under,
Opts.ignore_errors,
Opts.include,
Opts.omit,
Opts.output_xml,
Opts.quiet,
Opts.skip_empty,
]
+ GLOBAL_ARGS,
usage="[options] [modules]",
description="Generate an XML report of coverage results.",
),
}
def show_help(
error: str | None = None,
topic: str | None = None,
parser: optparse.OptionParser | None = None,
) -> None:
"""Display an error message, or the named topic."""
assert error or topic or parser
program_path = sys.argv[0]
if program_path.endswith(os.path.sep + "__main__.py"):
# The path is the main module of a package; get that path instead.
program_path = os.path.dirname(program_path)
program_name = os.path.basename(program_path)
if env.WINDOWS:
# entry_points={"console_scripts":...} on Windows makes files
# called coverage.exe, coverage3.exe, and coverage-3.5.exe. These
# invoke coverage-script.py, coverage3-script.py, and
# coverage-3.5-script.py. argv[0] is the .py file, but we want to
# get back to the original form.
auto_suffix = "-script.py"
if program_name.endswith(auto_suffix):
program_name = program_name[: -len(auto_suffix)]
help_params = dict(coverage.__dict__)
help_params["__url__"] = __url__
help_params["program_name"] = program_name
if CTRACER_FILE:
help_params["extension_modifier"] = "with C extension"
else:
help_params["extension_modifier"] = "without C extension"
if error:
print(error, file=sys.stderr)
print(f"Use '{program_name} help' for help.", file=sys.stderr)
elif parser:
print(parser.format_help().strip())
print()
else:
assert topic is not None
help_msg = textwrap.dedent(HELP_TOPICS.get(topic, "")).strip()
if help_msg:
print(help_msg.format(**help_params))
else:
print(f"Don't know topic {topic!r}")
print("Full documentation is at {__url__}".format(**help_params))
OK, ERR, FAIL_UNDER = 0, 1, 2
class CoverageScript:
"""The command-line interface to coverage.py."""
def __init__(self) -> None:
self.global_option = False
self.coverage: Coverage
def command_line(self, argv: list[str]) -> int:
"""The bulk of the command line interface to coverage.py.
`argv` is the argument list to process.
Returns 0 if all is well, 1 if something went wrong.
"""
# Collect the command-line options.
if not argv:
show_help(topic="minimum_help")
return OK
# The command syntax we parse depends on the first argument. Global
# switch syntax always starts with an option.
parser: optparse.OptionParser | None
self.global_option = argv[0].startswith("-")
if self.global_option:
parser = GlobalOptionParser()
else:
parser = COMMANDS.get(argv[0])
if not parser:
show_help(f"Unknown command: {argv[0]!r}")
return ERR
argv = argv[1:]
ok, options, args = parser.parse_args_ok(argv)
if not ok:
return ERR
assert options is not None
# Handle help and version.
if self.do_help(options, args, parser):
return OK
# Listify the list options.
source = unshell_list(options.source)
omit = unshell_list(options.omit)
include = unshell_list(options.include)
debug = unshell_list(options.debug)
contexts = unshell_list(options.contexts)
if options.concurrency is not None:
concurrency = options.concurrency.split(",")
else:
concurrency = None
# Do something.
self.coverage = Coverage(
data_file=options.data_file or DEFAULT_DATAFILE,
data_suffix=options.parallel_mode,
cover_pylib=options.pylib,
timid=options.timid,
branch=options.branch,
config_file=options.rcfile,
source=source,
omit=omit,
include=include,
debug=debug,
concurrency=concurrency,
check_preimported=True,
context=options.context,
messages=not options.quiet,
)
if options.action == "debug":
return self.do_debug(args)
elif options.action == "erase":
self.coverage.erase()
return OK
elif options.action == "run":
return self.do_run(options, args)
elif options.action == "combine":
if options.append:
self.coverage.load()
data_paths = args or None
self.coverage.combine(data_paths, strict=True, keep=bool(options.keep))
self.coverage.save()
return OK
# Remaining actions are reporting, with some common options.
report_args = dict(
morfs=unglob_args(args),
ignore_errors=options.ignore_errors,
omit=omit,
include=include,
contexts=contexts,
)
# We need to be able to import from the current directory, because
# plugins may try to, for example, to read Django settings.
sys.path.insert(0, "")
self.coverage.load()
total = None
if options.action == "report":
total = self.coverage.report(
precision=options.precision,
show_missing=options.show_missing,
skip_covered=options.skip_covered,
skip_empty=options.skip_empty,
sort=options.sort,
output_format=options.format,
**report_args,
)
elif options.action == "annotate":
self.coverage.annotate(directory=options.directory, **report_args)
elif options.action == "html":
total = self.coverage.html_report(
directory=options.directory,
precision=options.precision,
skip_covered=options.skip_covered,
skip_empty=options.skip_empty,
show_contexts=options.show_contexts,
title=options.title,
**report_args,
)
elif options.action == "xml":
total = self.coverage.xml_report(
outfile=options.outfile,
skip_empty=options.skip_empty,
**report_args,
)
elif options.action == "json":
total = self.coverage.json_report(
outfile=options.outfile,
pretty_print=options.pretty_print,
show_contexts=options.show_contexts,
**report_args,
)
elif options.action == "lcov":
total = self.coverage.lcov_report(
outfile=options.outfile,
**report_args,
)
else:
# There are no other possible actions.
raise AssertionError
if total is not None:
# Apply the command line fail-under options, and then use the config
# value, so we can get fail_under from the config file.
if options.fail_under is not None:
self.coverage.set_option("report:fail_under", options.fail_under)
if options.precision is not None:
self.coverage.set_option("report:precision", options.precision)
fail_under = cast(float, self.coverage.get_option("report:fail_under"))
precision = cast(int, self.coverage.get_option("report:precision"))
if should_fail_under(total, fail_under, precision):
msg = "total of {total} is less than fail-under={fail_under:.{p}f}".format(
total=display_covered(total, precision),
fail_under=fail_under,
p=precision,
)
print("Coverage failure:", msg)
return FAIL_UNDER
return OK
def do_help(
self,
options: optparse.Values,
args: list[str],
parser: optparse.OptionParser,
) -> bool:
"""Deal with help requests.
Return True if it handled the request, False if not.
"""
# Handle help.
if options.help:
if self.global_option:
show_help(topic="help")
else:
show_help(parser=parser)
return True
if options.action == "help":
if args:
for a in args:
parser_maybe = COMMANDS.get(a)
if parser_maybe is not None:
show_help(parser=parser_maybe)
else:
show_help(topic=a)
else:
show_help(topic="help")
return True
# Handle version.
if options.version:
show_help(topic="version")
return True
return False
def do_signal_save(self, _signum: int, _frame: types.FrameType | None) -> None:
"""Signal handler to save coverage report"""
print("Saving coverage data...", flush=True)
self.coverage.save()
def do_run(self, options: optparse.Values, args: list[str]) -> int:
"""Implementation of 'coverage run'."""
if not args:
if options.module:
# Specified -m with nothing else.
show_help("No module specified for -m")
return ERR
command_line = cast(str, self.coverage.get_option("run:command_line"))
if command_line is not None:
args = shlex.split(command_line)
if args and args[0] in {"-m", "--module"}:
options.module = True
args = args[1:]
if not args:
show_help("Nothing to do.")
return ERR
if options.append and self.coverage.get_option("run:parallel"):
show_help("Can't append to data files in parallel mode.")
return ERR
if options.concurrency == "multiprocessing":
# Can't set other run-affecting command line options with
# multiprocessing.
for opt_name in ["branch", "include", "omit", "pylib", "source", "timid"]:
# As it happens, all of these options have no default, meaning
# they will be None if they have not been specified.
if getattr(options, opt_name) is not None:
show_help(
"Options affecting multiprocessing must only be specified "
+ "in a configuration file.\n"
+ f"Remove --{opt_name} from the command line.",
)
return ERR
os.environ["COVERAGE_RUN"] = "true"
runner = PyRunner(args, as_module=bool(options.module))
runner.prepare()
if options.append:
self.coverage.load()
if options.save_signal:
if env.WINDOWS:
show_help("--save-signal is not supported on Windows.")
return ERR
sig = getattr(signal, f"SIG{options.save_signal}")
signal.signal(sig, self.do_signal_save)
# Run the script.
self.coverage.start()
code_ran = True
try:
runner.run()
except NoSource:
code_ran = False
raise
finally:
self.coverage.stop()
if code_ran:
self.coverage.save()
return OK
def do_debug(self, args: list[str]) -> int:
"""Implementation of 'coverage debug'."""
if not args:
show_help("What information would you like: config, data, sys, premain, pybehave?")
return ERR
if args[1:]:
show_help("Only one topic at a time, please")
return ERR
if args[0] == "sys":
write_formatted_info(print, "sys", self.coverage.sys_info())
elif args[0] == "data":
print(info_header("data"))
data_file = self.coverage.config.data_file
debug_data_file(data_file)
for filename in combinable_files(data_file):
print("-----")
debug_data_file(filename)
elif args[0] == "config":
write_formatted_info(print, "config", self.coverage.config.debug_info())
elif args[0] == "premain":
print(info_header("premain"))
print(short_stack(full=True))
elif args[0] == "pybehave":
write_formatted_info(print, "pybehave", env.debug_info())
else:
show_help(f"Don't know what you mean by {args[0]!r}")
return ERR
return OK
def unshell_list(s: str) -> list[str] | None:
"""Turn a command-line argument into a list."""
if not s:
return None
if env.WINDOWS:
# When running coverage.py as coverage.exe, some of the behavior
# of the shell is emulated: wildcards are expanded into a list of
# file names. So you have to single-quote patterns on the command
# line, but (not) helpfully, the single quotes are included in the
# argument, so we have to strip them off here.
s = s.strip("'")
return s.split(",")
def unglob_args(args: list[str]) -> list[str]:
"""Interpret shell wildcards for platforms that need it."""
if env.WINDOWS:
globbed = []
for arg in args:
if "?" in arg or "*" in arg:
globbed.extend(glob.glob(arg))
else:
globbed.append(arg)
args = globbed
return args
HELP_TOPICS = {
"help": """\
Coverage.py, version {__version__} {extension_modifier}
Measure, collect, and report on code coverage in Python programs.
usage: {program_name} [options] [args]
Commands:
annotate Annotate source files with execution information.
combine Combine a number of data files.
debug Display information about the internals of coverage.py
erase Erase previously collected coverage data.
help Get help on using coverage.py.
html Create an HTML report.
json Create a JSON report of coverage results.
lcov Create an LCOV report of coverage results.
report Report coverage stats on modules.
run Run a Python program and measure code execution.
xml Create an XML report of coverage results.
Use "{program_name} help " for detailed help on any command.
""",
"minimum_help": oneline(
"""
Code coverage for Python, version {__version__} {extension_modifier}.
Use '{program_name} help' for help.
"""
),
"version": "Coverage.py, version {__version__} {extension_modifier}",
}
def main(argv: list[str] | None = None) -> int | None:
"""The main entry point to coverage.py.
This is installed as the script entry point.
"""
if argv is None:
argv = sys.argv[1:]
try:
status = CoverageScript().command_line(argv)
except _ExceptionDuringRun as err:
# An exception was caught while running the product code. The
# sys.exc_info() return tuple is packed into an _ExceptionDuringRun
# exception.
traceback.print_exception(*err.args) # pylint: disable=no-value-for-parameter
status = ERR
except CoverageException as err:
# A controlled error inside coverage.py: print the message to the user.
msg = err.args[0]
if err.slug:
msg = f"{msg.rstrip('.')}; see {__url__}/messages.html#error-{err.slug}"
print(msg)
status = ERR
except SystemExit as err:
# The user called `sys.exit()`. Exit with their argument, if any.
if err.args:
status = err.args[0]
else:
status = None
return status
# Profiling using ox_profile. Install it from GitHub:
# pip install git+https://github.com/emin63/ox_profile.git
#
# $set_env.py: COVERAGE_PROFILE - Set to use ox_profile.
_profile = os.getenv("COVERAGE_PROFILE")
if _profile: # pragma: debugging
from ox_profile.core.launchers import SimpleLauncher # pylint: disable=import-error
original_main = main
def main( # pylint: disable=function-redefined
argv: list[str] | None = None,
) -> int | None:
"""A wrapper around main that profiles."""
profiler = SimpleLauncher.launch()
try:
return original_main(argv)
finally:
data, _ = profiler.query(re_filter="coverage", max_records=100)
print(profiler.show(query=data, limit=100, sep="", col=""))
profiler.cancel()
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/collector.py 0000644 0001751 0001751 00000045541 15073731535 017216 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Raw data collector for coverage.py."""
from __future__ import annotations
import contextlib
import functools
import os
import sys
from collections.abc import Mapping
from types import FrameType
from typing import Any, Callable, TypeVar, cast
from coverage import env
from coverage.config import CoverageConfig
from coverage.core import Core
from coverage.data import CoverageData
from coverage.debug import short_stack
from coverage.exceptions import ConfigError
from coverage.misc import human_sorted_items, isolate_module
from coverage.plugin import CoveragePlugin
from coverage.types import (
TArc,
TCheckIncludeFn,
TFileDisposition,
Tracer,
TShouldStartContextFn,
TShouldTraceFn,
TTraceData,
TTraceFn,
TWarnFn,
)
os = isolate_module(os)
T = TypeVar("T")
class Collector:
"""Collects trace data.
Creates a Tracer object for each thread, since they track stack
information. Each Tracer points to the same shared data, contributing
traced data points.
When the Collector is started, it creates a Tracer for the current thread,
and installs a function to create Tracers for each new thread started.
When the Collector is stopped, all active Tracers are stopped.
Threads started while the Collector is stopped will never have Tracers
associated with them.
"""
# The stack of active Collectors. Collectors are added here when started,
# and popped when stopped. Collectors on the stack are paused when not
# the top, and resumed when they become the top again.
_collectors: list[Collector] = []
# The concurrency settings we support here.
LIGHT_THREADS = {"greenlet", "eventlet", "gevent"}
def __init__(
self,
core: Core,
should_trace: TShouldTraceFn,
check_include: TCheckIncludeFn,
should_start_context: TShouldStartContextFn | None,
file_mapper: Callable[[str], str],
branch: bool,
warn: TWarnFn,
concurrency: list[str],
) -> None:
"""Create a collector.
`should_trace` is a function, taking a file name and a frame, and
returning a `coverage.FileDisposition object`.
`check_include` is a function taking a file name and a frame. It returns
a boolean: True if the file should be traced, False if not.
`should_start_context` is a function taking a frame, and returning a
string. If the frame should be the start of a new context, the string
is the new context. If the frame should not be the start of a new
context, return None.
`file_mapper` is a function taking a filename, and returning a Unicode
filename. The result is the name that will be recorded in the data
file.
If `branch` is true, then branches will be measured. This involves
collecting data on which statements followed each other (arcs). Use
`get_arc_data` to get the arc data.
`warn` is a warning function, taking a single string message argument
and an optional slug argument which will be a string or None, to be
used if a warning needs to be issued.
`concurrency` is a list of strings indicating the concurrency libraries
in use. Valid values are "greenlet", "eventlet", "gevent", or "thread"
(the default). "thread" can be combined with one of the other three.
Other values are ignored.
"""
self.core = core
self.should_trace = should_trace
self.check_include = check_include
self.should_start_context = should_start_context
self.file_mapper = file_mapper
self.branch = branch
self.warn = warn
self.concurrency = concurrency
assert isinstance(self.concurrency, list), f"Expected a list: {self.concurrency!r}"
self.pid = os.getpid()
self.covdata: CoverageData
self.threading = None
self.static_context: str | None = None
self.origin = short_stack()
self.concur_id_func = None
# We can handle a few concurrency options here, but only one at a time.
concurrencies = set(self.concurrency)
unknown = concurrencies - CoverageConfig.CONCURRENCY_CHOICES
if unknown:
show = ", ".join(sorted(unknown))
raise ConfigError(f"Unknown concurrency choices: {show}")
light_threads = concurrencies & self.LIGHT_THREADS
if len(light_threads) > 1:
show = ", ".join(sorted(light_threads))
raise ConfigError(f"Conflicting concurrency settings: {show}")
do_threading = False
tried = "nothing" # to satisfy pylint
try:
if "greenlet" in concurrencies:
tried = "greenlet"
import greenlet
self.concur_id_func = greenlet.getcurrent
elif "eventlet" in concurrencies:
tried = "eventlet"
import eventlet.greenthread
self.concur_id_func = eventlet.greenthread.getcurrent
elif "gevent" in concurrencies:
tried = "gevent"
import gevent
self.concur_id_func = gevent.getcurrent
if "thread" in concurrencies:
do_threading = True
except ImportError as ex:
msg = f"Couldn't trace with concurrency={tried}, the module isn't installed."
raise ConfigError(msg) from ex
if self.concur_id_func and not hasattr(core.tracer_class, "concur_id_func"):
raise ConfigError(
"Can't support concurrency={} with {}, only threads are supported.".format(
tried,
self.tracer_name(),
),
)
if do_threading or not concurrencies:
# It's important to import threading only if we need it. If
# it's imported early, and the program being measured uses
# gevent, then gevent's monkey-patching won't work properly.
import threading
self.threading = threading
self.reset()
def __repr__(self) -> str:
return f""
def use_data(self, covdata: CoverageData, context: str | None) -> None:
"""Use `covdata` for recording data."""
self.covdata = covdata
self.static_context = context
self.covdata.set_context(self.static_context)
def tracer_name(self) -> str:
"""Return the class name of the tracer we're using."""
return self.core.tracer_class.__name__
def _clear_data(self) -> None:
"""Clear out existing data, but stay ready for more collection."""
# We used to use self.data.clear(), but that would remove filename
# keys and data values that were still in use higher up the stack
# when we are called as part of switch_context.
with self.data_lock or contextlib.nullcontext():
for d in self.data.values():
d.clear()
for tracer in self.tracers:
tracer.reset_activity()
def reset(self) -> None:
"""Clear collected data, and prepare to collect more."""
self.data_lock = self.threading.Lock() if self.threading else None
# The trace data we are collecting.
self.data: TTraceData = {}
# A dictionary mapping file names to file tracer plugin names that will
# handle them.
self.file_tracers: dict[str, str] = {}
self.disabled_plugins: set[str] = set()
# The .should_trace_cache attribute is a cache from file names to
# coverage.FileDisposition objects, or None. When a file is first
# considered for tracing, a FileDisposition is obtained from
# Coverage.should_trace. Its .trace attribute indicates whether the
# file should be traced or not. If it should be, a plugin with dynamic
# file names can decide not to trace it based on the dynamic file name
# being excluded by the inclusion rules, in which case the
# FileDisposition will be replaced by None in the cache.
if env.PYPY:
import __pypy__ # pylint: disable=import-error
# Alex Gaynor said:
# should_trace_cache is a strictly growing key: once a key is in
# it, it never changes. Further, the keys used to access it are
# generally constant, given sufficient context. That is to say, at
# any given point _trace() is called, pypy is able to know the key.
# This is because the key is determined by the physical source code
# line, and that's invariant with the call site.
#
# This property of a dict with immutable keys, combined with
# call-site-constant keys is a match for PyPy's module dict,
# which is optimized for such workloads.
#
# This gives a 20% benefit on the workload described at
# https://bitbucket.org/pypy/pypy/issue/1871/10x-slower-than-cpython-under-coverage
self.should_trace_cache = __pypy__.newdict("module")
else:
self.should_trace_cache = {}
# Our active Tracers.
self.tracers: list[Tracer] = []
self._clear_data()
def lock_data(self) -> None:
"""Lock self.data_lock, for use by the C tracer."""
if self.data_lock is not None:
self.data_lock.acquire()
def unlock_data(self) -> None:
"""Unlock self.data_lock, for use by the C tracer."""
if self.data_lock is not None:
self.data_lock.release()
def _start_tracer(self) -> TTraceFn | None:
"""Start a new Tracer object, and store it in self.tracers."""
tracer = self.core.tracer_class(**self.core.tracer_kwargs)
tracer.data = self.data
tracer.lock_data = self.lock_data
tracer.unlock_data = self.unlock_data
tracer.trace_arcs = self.branch
tracer.should_trace = self.should_trace
tracer.should_trace_cache = self.should_trace_cache
tracer.warn = self.warn
if hasattr(tracer, "concur_id_func"):
tracer.concur_id_func = self.concur_id_func
if hasattr(tracer, "file_tracers"):
tracer.file_tracers = self.file_tracers
if hasattr(tracer, "threading"):
tracer.threading = self.threading
if hasattr(tracer, "check_include"):
tracer.check_include = self.check_include
if hasattr(tracer, "should_start_context"):
tracer.should_start_context = self.should_start_context
if hasattr(tracer, "switch_context"):
tracer.switch_context = self.switch_context
if hasattr(tracer, "disable_plugin"):
tracer.disable_plugin = self.disable_plugin
fn = tracer.start()
self.tracers.append(tracer)
return fn
# The trace function has to be set individually on each thread before
# execution begins. Ironically, the only support the threading module has
# for running code before the thread main is the tracing function. So we
# install this as a trace function, and the first time it's called, it does
# the real trace installation.
#
# New in 3.12: threading.settrace_all_threads: https://github.com/python/cpython/pull/96681
def _installation_trace(self, frame: FrameType, event: str, arg: Any) -> TTraceFn | None:
"""Called on new threads, installs the real tracer."""
# Remove ourselves as the trace function.
sys.settrace(None)
# Install the real tracer.
fn: TTraceFn | None = self._start_tracer()
# Invoke the real trace function with the current event, to be sure
# not to lose an event.
if fn:
fn = fn(frame, event, arg)
# Return the new trace function to continue tracing in this scope.
return fn
def start(self) -> None:
"""Start collecting trace information."""
# We may be a new collector in a forked process. The old process'
# collectors will be in self._collectors, but they won't be usable.
# Find them and discard them.
keep_collectors = []
for c in self._collectors:
if c.pid == self.pid:
keep_collectors.append(c)
else:
c.post_fork()
self._collectors[:] = keep_collectors
if self._collectors:
self._collectors[-1].pause()
self.tracers = []
try:
# Install the tracer on this thread.
self._start_tracer()
except:
if self._collectors:
self._collectors[-1].resume()
raise
# If _start_tracer succeeded, then we add ourselves to the global
# stack of collectors.
self._collectors.append(self)
# Install our installation tracer in threading, to jump-start other
# threads.
if self.core.systrace and self.threading:
self.threading.settrace(self._installation_trace)
def stop(self) -> None:
"""Stop collecting trace information."""
assert self._collectors
if self._collectors[-1] is not self:
print("self._collectors:")
for c in self._collectors:
print(f" {c!r}\n{c.origin}")
assert self._collectors[-1] is self, (
f"Expected current collector to be {self!r}, but it's {self._collectors[-1]!r}"
)
self.pause()
# Remove this Collector from the stack, and resume the one underneath (if any).
self._collectors.pop()
if self._collectors:
self._collectors[-1].resume()
def pause(self) -> None:
"""Pause tracing, but be prepared to `resume`."""
for tracer in self.tracers:
tracer.stop()
stats = tracer.get_stats()
if stats:
print(f"\nCoverage.py {tracer.__class__.__name__} stats:")
for k, v in human_sorted_items(stats.items()):
print(f"{k:>20}: {v}")
if self.threading:
self.threading.settrace(None)
def resume(self) -> None:
"""Resume tracing after a `pause`."""
for tracer in self.tracers:
tracer.start()
if self.core.systrace:
if self.threading:
self.threading.settrace(self._installation_trace)
else:
self._start_tracer()
def post_fork(self) -> None:
"""After a fork, tracers might need to adjust."""
for tracer in self.tracers:
if hasattr(tracer, "post_fork"):
tracer.post_fork()
def _activity(self) -> bool:
"""Has any activity been traced?
Returns a boolean, True if any trace function was invoked.
"""
return any(tracer.activity() for tracer in self.tracers)
def switch_context(self, new_context: str | None) -> None:
"""Switch to a new dynamic context."""
context: str | None
self.flush_data()
if self.static_context:
context = self.static_context
if new_context:
context += "|" + new_context
else:
context = new_context
self.covdata.set_context(context)
def disable_plugin(self, disposition: TFileDisposition) -> None:
"""Disable the plugin mentioned in `disposition`."""
file_tracer = disposition.file_tracer
assert file_tracer is not None
plugin = file_tracer._coverage_plugin
plugin_name = plugin._coverage_plugin_name
self.warn(f"Disabling plug-in {plugin_name!r} due to previous exception")
plugin._coverage_enabled = False
disposition.trace = False
@functools.cache # pylint: disable=method-cache-max-size-none
def cached_mapped_file(self, filename: str) -> str:
"""A locally cached version of file names mapped through file_mapper."""
return self.file_mapper(filename)
def mapped_file_dict(self, d: Mapping[str, T]) -> dict[str, T]:
"""Return a dict like d, but with keys modified by file_mapper."""
# The call to list(items()) ensures that the GIL protects the dictionary
# iterator against concurrent modifications by tracers running
# in other threads. We try three times in case of concurrent
# access, hoping to get a clean copy.
runtime_err = None
for _ in range(3): # pragma: part covered
try:
items = list(d.items())
except RuntimeError as ex: # pragma: cant happen
runtime_err = ex
else:
break
else: # pragma: cant happen
assert isinstance(runtime_err, Exception)
raise runtime_err
return {self.cached_mapped_file(k): v for k, v in items if v}
def plugin_was_disabled(self, plugin: CoveragePlugin) -> None:
"""Record that `plugin` was disabled during the run."""
self.disabled_plugins.add(plugin._coverage_plugin_name)
def flush_data(self) -> bool:
"""Save the collected data to our associated `CoverageData`.
Data may have also been saved along the way. This forces the
last of the data to be saved.
Returns True if there was data to save, False if not.
"""
if not self._activity():
return False
if self.branch:
if self.core.packed_arcs:
# Unpack the line number pairs packed into integers. See
# tracer.c:CTracer_record_pair for the C code that creates
# these packed ints.
arc_data: dict[str, list[TArc]] = {}
packed_data = cast(dict[str, set[int]], self.data)
# The list() here and in the inner loop are to get a clean copy
# even as tracers are continuing to add data.
for fname, packeds in list(packed_data.items()):
tuples = []
for packed in list(packeds):
l1 = packed & 0xFFFFF
l2 = (packed & (0xFFFFF << 20)) >> 20
if packed & (1 << 40):
l1 *= -1
if packed & (1 << 41):
l2 *= -1
tuples.append((l1, l2))
arc_data[fname] = tuples
else:
arc_data = cast(dict[str, list[TArc]], self.data)
self.covdata.add_arcs(self.mapped_file_dict(arc_data))
else:
line_data = cast(dict[str, set[int]], self.data)
self.covdata.add_lines(self.mapped_file_dict(line_data))
file_tracers = {
k: v for k, v in self.file_tracers.items() if v not in self.disabled_plugins
}
self.covdata.add_file_tracers(self.mapped_file_dict(file_tracers))
self._clear_data()
return True
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/config.py 0000644 0001751 0001751 00000061344 15073731535 016474 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Config file for coverage.py"""
from __future__ import annotations
import base64
import collections
import configparser
import copy
import json
import os
import os.path
import re
from collections.abc import Iterable
from typing import Any, Callable, Final, Mapping
from coverage.exceptions import ConfigError
from coverage.misc import human_sorted_items, isolate_module, substitute_variables
from coverage.tomlconfig import TomlConfigParser, TomlDecodeError
from coverage.types import (
TConfigSectionIn,
TConfigSectionOut,
TConfigurable,
TConfigValueIn,
TConfigValueOut,
TPluginConfig,
)
os = isolate_module(os)
class HandyConfigParser(configparser.ConfigParser):
"""Our specialization of ConfigParser."""
def __init__(self, our_file: bool) -> None:
"""Create the HandyConfigParser.
`our_file` is True if this config file is specifically for coverage,
False if we are examining another config file (tox.ini, setup.cfg)
for possible settings.
"""
super().__init__(interpolation=None)
self.section_prefixes = ["coverage:"]
if our_file:
self.section_prefixes.append("")
def read( # type: ignore[override]
self,
filenames: Iterable[str],
encoding_unused: str | None = None,
) -> list[str]:
"""Read a file name as UTF-8 configuration data."""
return super().read(filenames, encoding="utf-8")
def real_section(self, section: str) -> str | None:
"""Get the actual name of a section."""
for section_prefix in self.section_prefixes:
real_section = section_prefix + section
has = super().has_section(real_section)
if has:
return real_section
return None
def has_option(self, section: str, option: str) -> bool: # type: ignore[override]
real_section = self.real_section(section)
if real_section is not None:
return super().has_option(real_section, option)
return False
def has_section(self, section: str) -> bool: # type: ignore[override]
return bool(self.real_section(section))
def options(self, section: str) -> list[str]: # type: ignore[override]
real_section = self.real_section(section)
if real_section is not None:
return super().options(real_section)
raise ConfigError(f"No section: {section!r}")
def get_section(self, section: str) -> TConfigSectionOut:
"""Get the contents of a section, as a dictionary."""
d: dict[str, TConfigValueOut] = {}
for opt in self.options(section):
d[opt] = self.get(section, opt)
return d
def get(self, section: str, option: str, *args: Any, **kwargs: Any) -> str: # type: ignore
"""Get a value, replacing environment variables also.
The arguments are the same as `ConfigParser.get`, but in the found
value, ``$WORD`` or ``${WORD}`` are replaced by the value of the
environment variable ``WORD``.
Returns the finished value.
"""
for section_prefix in self.section_prefixes:
real_section = section_prefix + section
if super().has_option(real_section, option):
break
else:
raise ConfigError(f"No option {option!r} in section: {section!r}")
v: str = super().get(real_section, option, *args, **kwargs)
v = substitute_variables(v, os.environ)
return v
def getfile(self, section: str, option: str) -> str:
"""Fix up a file path setting."""
path = self.get(section, option)
return process_file_value(path)
def getlist(self, section: str, option: str) -> list[str]:
"""Read a list of strings.
The value of `section` and `option` is treated as a comma- and newline-
separated list of strings. Each value is stripped of white space.
Returns the list of strings.
"""
value_list = self.get(section, option)
values = []
for value_line in value_list.split("\n"):
for value in value_line.split(","):
value = value.strip()
if value:
values.append(value)
return values
def getregexlist(self, section: str, option: str) -> list[str]:
"""Read a list of full-line regexes.
The value of `section` and `option` is treated as a newline-separated
list of regexes. Each value is stripped of white space.
Returns the list of strings.
"""
line_list = self.get(section, option)
return process_regexlist(section, option, line_list.splitlines())
TConfigParser = HandyConfigParser | TomlConfigParser
# The default line exclusion regexes.
DEFAULT_EXCLUDE = [
r"#\s*(pragma|PRAGMA)[:\s]?\s*(no|NO)\s*(cover|COVER)",
r"^\s*(((async )?def .*?)?\)(\s*->.*?)?:\s*)?\.\.\.\s*(#|$)",
r"if (typing\.)?TYPE_CHECKING:",
]
# The default partial branch regexes, to be modified by the user.
DEFAULT_PARTIAL = [
r"#\s*(pragma|PRAGMA)[:\s]?\s*(no|NO)\s*(branch|BRANCH)",
]
# The default partial branch regexes, based on Python semantics.
# These are any Python branching constructs that can't actually execute all
# their branches.
DEFAULT_PARTIAL_ALWAYS = [
"while (True|1|False|0):",
"if (True|1|False|0):",
]
class CoverageConfig(TConfigurable, TPluginConfig):
"""Coverage.py configuration.
The attributes of this class are the various settings that control the
operation of coverage.py.
"""
# pylint: disable=too-many-instance-attributes
def __init__(self) -> None:
"""Initialize the configuration attributes to their defaults."""
# Metadata about the config.
# We tried to read these config files.
self.config_files_attempted: list[str] = []
# We did read these config files, but maybe didn't find any content for us.
self.config_files_read: list[str] = []
# The file that gave us our configuration.
self.config_file: str | None = None
self._config_contents: bytes | None = None
# Defaults for [run] and [report]
self._include = None
self._omit = None
# Defaults for [run]
self.branch = False
self.command_line: str | None = None
self.concurrency: list[str] = []
self.context: str | None = None
self.core: str | None = None
self.cover_pylib = False
self.data_file = ".coverage"
self.debug: list[str] = []
self.debug_file: str | None = None
self.disable_warnings: list[str] = []
self.dynamic_context: str | None = None
self.parallel = False
self.patch: list[str] = []
self.plugins: list[str] = []
self.relative_files = False
self.run_include: list[str] = []
self.run_omit: list[str] = []
self.sigterm = False
self.source: list[str] | None = None
self.source_pkgs: list[str] = []
self.source_dirs: list[str] = []
self.timid = False
self._crash: str | None = None
# Defaults for [report]
self.exclude_list = DEFAULT_EXCLUDE[:]
self.exclude_also: list[str] = []
self.fail_under = 0.0
self.format: str | None = None
self.ignore_errors = False
self.include_namespace_packages = False
self.report_include: list[str] | None = None
self.report_omit: list[str] | None = None
self.partial_always_list = DEFAULT_PARTIAL_ALWAYS[:]
self.partial_list = DEFAULT_PARTIAL[:]
self.partial_also: list[str] = []
self.precision = 0
self.report_contexts: list[str] | None = None
self.show_missing = False
self.skip_covered = False
self.skip_empty = False
self.sort: str | None = None
# Defaults for [html]
self.extra_css: str | None = None
self.html_dir = "htmlcov"
self.html_skip_covered: bool | None = None
self.html_skip_empty: bool | None = None
self.html_title = "Coverage report"
self.show_contexts = False
# Defaults for [xml]
self.xml_output = "coverage.xml"
self.xml_package_depth = 99
# Defaults for [json]
self.json_output = "coverage.json"
self.json_pretty_print = False
self.json_show_contexts = False
# Defaults for [lcov]
self.lcov_output = "coverage.lcov"
self.lcov_line_checksums = False
# Defaults for [paths]
self.paths: dict[str, list[str]] = {}
# Options for plugins
self.plugin_options: dict[str, TConfigSectionOut] = {}
MUST_BE_LIST = {
"debug",
"concurrency",
"plugins",
"report_omit",
"report_include",
"run_omit",
"run_include",
"patch",
}
# File paths to make absolute during serialization.
# The pairs are (config_key, must_exist).
SERIALIZE_ABSPATH = {
("data_file", False),
("debug_file", False),
# `source` can be directories or modules, so don't abspath it if it
# doesn't exist.
("source", True),
("source_dirs", False),
}
def from_args(self, **kwargs: TConfigValueIn) -> None:
"""Read config values from `kwargs`."""
for k, v in kwargs.items():
if v is not None:
if k in self.MUST_BE_LIST and isinstance(v, str):
v = [v]
setattr(self, k, v)
def from_file(self, filename: str, warn: Callable[[str], None], our_file: bool) -> bool:
"""Read configuration from a .rc file.
`filename` is a file name to read.
`our_file` is True if this config file is specifically for coverage,
False if we are examining another config file (tox.ini, setup.cfg)
for possible settings.
Returns True or False, whether the file could be read, and it had some
coverage.py settings in it.
"""
_, ext = os.path.splitext(filename)
cp: TConfigParser
if ext == ".toml":
cp = TomlConfigParser(our_file)
else:
cp = HandyConfigParser(our_file)
self.config_files_attempted.append(os.path.abspath(filename))
try:
files_read = cp.read(filename)
except (configparser.Error, TomlDecodeError) as err:
raise ConfigError(f"Couldn't read config file {filename}: {err}") from err
if not files_read:
return False
self.config_files_read.extend(map(os.path.abspath, files_read))
any_set = False
try:
for option_spec in self.CONFIG_FILE_OPTIONS:
was_set = self._set_attr_from_config_option(cp, *option_spec)
if was_set:
any_set = True
except ValueError as err:
raise ConfigError(f"Couldn't read config file {filename}: {err}") from err
# Check that there are no unrecognized options.
all_options = collections.defaultdict(set)
for option_spec in self.CONFIG_FILE_OPTIONS:
section, option = option_spec[1].split(":")
all_options[section].add(option)
for section, options in all_options.items():
real_section = cp.real_section(section)
if real_section:
for unknown in set(cp.options(section)) - options:
warn(
"Unrecognized option '[{}] {}=' in config file {}".format(
real_section,
unknown,
filename,
),
)
# [paths] is special
if cp.has_section("paths"):
for option in cp.options("paths"):
self.paths[option] = cp.getlist("paths", option)
any_set = True
# plugins can have options
for plugin in self.plugins:
if cp.has_section(plugin):
self.plugin_options[plugin] = cp.get_section(plugin)
any_set = True
# Was this file used as a config file? If it's specifically our file,
# then it was used. If we're piggybacking on someone else's file,
# then it was only used if we found some settings in it.
if our_file:
used = True
else:
used = any_set
if used:
self.config_file = os.path.abspath(filename)
with open(filename, "rb") as f:
self._config_contents = f.read()
return used
def copy(self) -> CoverageConfig:
"""Return a copy of the configuration."""
return copy.deepcopy(self)
CONCURRENCY_CHOICES: Final[set[str]] = {
"thread",
"gevent",
"greenlet",
"eventlet",
"multiprocessing",
}
CONFIG_FILE_OPTIONS = [
# These are *args for _set_attr_from_config_option:
# (attr, where, type_="")
#
# attr is the attribute to set on the CoverageConfig object.
# where is the section:name to read from the configuration file.
# type_ is the optional type to apply, by using .getTYPE to read the
# configuration value from the file.
#
# [run]
("branch", "run:branch", "boolean"),
("command_line", "run:command_line"),
("concurrency", "run:concurrency", "list"),
("context", "run:context"),
("core", "run:core"),
("cover_pylib", "run:cover_pylib", "boolean"),
("data_file", "run:data_file", "file"),
("debug", "run:debug", "list"),
("debug_file", "run:debug_file", "file"),
("disable_warnings", "run:disable_warnings", "list"),
("dynamic_context", "run:dynamic_context"),
("parallel", "run:parallel", "boolean"),
("patch", "run:patch", "list"),
("plugins", "run:plugins", "list"),
("relative_files", "run:relative_files", "boolean"),
("run_include", "run:include", "list"),
("run_omit", "run:omit", "list"),
("sigterm", "run:sigterm", "boolean"),
("source", "run:source", "list"),
("source_pkgs", "run:source_pkgs", "list"),
("source_dirs", "run:source_dirs", "list"),
("timid", "run:timid", "boolean"),
("_crash", "run:_crash"),
#
# [report]
("exclude_list", "report:exclude_lines", "regexlist"),
("exclude_also", "report:exclude_also", "regexlist"),
("fail_under", "report:fail_under", "float"),
("format", "report:format"),
("ignore_errors", "report:ignore_errors", "boolean"),
("include_namespace_packages", "report:include_namespace_packages", "boolean"),
("partial_always_list", "report:partial_branches_always", "regexlist"),
("partial_list", "report:partial_branches", "regexlist"),
("partial_also", "report:partial_also", "regexlist"),
("precision", "report:precision", "int"),
("report_contexts", "report:contexts", "list"),
("report_include", "report:include", "list"),
("report_omit", "report:omit", "list"),
("show_missing", "report:show_missing", "boolean"),
("skip_covered", "report:skip_covered", "boolean"),
("skip_empty", "report:skip_empty", "boolean"),
("sort", "report:sort"),
#
# [html]
("extra_css", "html:extra_css"),
("html_dir", "html:directory", "file"),
("html_skip_covered", "html:skip_covered", "boolean"),
("html_skip_empty", "html:skip_empty", "boolean"),
("html_title", "html:title"),
("show_contexts", "html:show_contexts", "boolean"),
#
# [xml]
("xml_output", "xml:output", "file"),
("xml_package_depth", "xml:package_depth", "int"),
#
# [json]
("json_output", "json:output", "file"),
("json_pretty_print", "json:pretty_print", "boolean"),
("json_show_contexts", "json:show_contexts", "boolean"),
#
# [lcov]
("lcov_output", "lcov:output", "file"),
("lcov_line_checksums", "lcov:line_checksums", "boolean"),
]
def _set_attr_from_config_option(
self,
cp: TConfigParser,
attr: str,
where: str,
type_: str = "",
) -> bool:
"""Set an attribute on self if it exists in the ConfigParser.
Returns True if the attribute was set.
"""
section, option = where.split(":")
if cp.has_option(section, option):
method = getattr(cp, f"get{type_}")
setattr(self, attr, method(section, option))
return True
return False
def get_plugin_options(self, plugin: str) -> TConfigSectionOut:
"""Get a dictionary of options for the plugin named `plugin`."""
return self.plugin_options.get(plugin, {})
def set_option(self, option_name: str, value: TConfigValueIn | TConfigSectionIn) -> None:
"""Set an option in the configuration.
`option_name` is a colon-separated string indicating the section and
option name. For example, the ``branch`` option in the ``[run]``
section of the config file would be indicated with `"run:branch"`.
`value` is the new value for the option.
"""
# Special-cased options.
if option_name == "paths":
# This is ugly, but type-checks and ensures the values are close
# to right.
self.paths = {}
assert isinstance(value, Mapping)
for k, v in value.items():
assert isinstance(v, Iterable)
self.paths[k] = list(v)
return
# Check all the hard-coded options.
for option_spec in self.CONFIG_FILE_OPTIONS:
attr, where = option_spec[:2]
if where == option_name:
setattr(self, attr, value)
return
# See if it's a plugin option.
plugin_name, _, key = option_name.partition(":")
if key and plugin_name in self.plugins:
self.plugin_options.setdefault(plugin_name, {})[key] = value # type: ignore[index]
return
# If we get here, we didn't find the option.
raise ConfigError(f"No such option: {option_name!r}")
def get_option(self, option_name: str) -> TConfigValueOut | None:
"""Get an option from the configuration.
`option_name` is a colon-separated string indicating the section and
option name. For example, the ``branch`` option in the ``[run]``
section of the config file would be indicated with `"run:branch"`.
Returns the value of the option.
"""
# Special-cased options.
if option_name == "paths":
return self.paths
# Check all the hard-coded options.
for option_spec in self.CONFIG_FILE_OPTIONS:
attr, where = option_spec[:2]
if where == option_name:
return getattr(self, attr) # type: ignore[no-any-return]
# See if it's a plugin option.
plugin_name, _, key = option_name.partition(":")
if key and plugin_name in self.plugins:
return self.plugin_options.get(plugin_name, {}).get(key)
# If we get here, we didn't find the option.
raise ConfigError(f"No such option: {option_name!r}")
def post_process(self) -> None:
"""Make final adjustments to settings to make them usable."""
self.paths = {k: [process_file_value(f) for f in v] for k, v in self.paths.items()}
self.exclude_list += self.exclude_also
self.partial_list += self.partial_also
if "subprocess" in self.patch:
self.parallel = True
def debug_info(self) -> list[tuple[str, Any]]:
"""Make a list of (name, value) pairs for writing debug info."""
return human_sorted_items((k, v) for k, v in self.__dict__.items() if not k.startswith("_"))
def serialize(self) -> str:
"""Convert to a string that can be ingested with `deserialize`.
File paths used by `coverage run` are made absolute to ensure the
deserialized config will refer to the same files.
"""
data = {k: v for k, v in self.__dict__.items() if not k.startswith("_")}
for k, must_exist in self.SERIALIZE_ABSPATH:
abs_fn = abs_path_if_exists if must_exist else os.path.abspath
v = data[k]
if isinstance(v, list):
v = list(map(abs_fn, v))
elif isinstance(v, str):
v = abs_fn(v)
data[k] = v
return base64.b64encode(json.dumps(data).encode()).decode()
@classmethod
def deserialize(cls, config_str: str) -> CoverageConfig:
"""Take a string from `serialize`, and make a CoverageConfig."""
data = json.loads(base64.b64decode(config_str.encode()).decode())
config = cls()
config.__dict__.update(data)
return config
def process_file_value(path: str) -> str:
"""Make adjustments to a file path to make it usable."""
return os.path.expanduser(path)
def abs_path_if_exists(path: str) -> str:
"""os.path.abspath, but only if the path exists."""
if os.path.exists(path):
return os.path.abspath(path)
else:
return path
def process_regexlist(name: str, option: str, values: list[str]) -> list[str]:
"""Check the values in a regex list and keep the non-blank ones."""
value_list = []
for value in values:
value = value.strip()
try:
re.compile(value)
except re.error as e:
raise ConfigError(f"Invalid [{name}].{option} value {value!r}: {e}") from e
if value:
value_list.append(value)
return value_list
def config_files_to_try(config_file: bool | str) -> list[tuple[str, bool, bool]]:
"""What config files should we try to read?
Returns a list of tuples:
(filename, is_our_file, was_file_specified)
"""
# Some API users were specifying ".coveragerc" to mean the same as
# True, so make it so.
if config_file == ".coveragerc":
config_file = True
specified_file = config_file is not True
if not specified_file:
# No file was specified. Check COVERAGE_RCFILE.
rcfile = os.getenv("COVERAGE_RCFILE")
if rcfile:
config_file = rcfile
specified_file = True
if not specified_file:
# Still no file specified. Default to .coveragerc
config_file = ".coveragerc"
assert isinstance(config_file, str)
files_to_try = [
(config_file, True, specified_file),
("setup.cfg", False, False),
("tox.ini", False, False),
("pyproject.toml", False, False),
]
return files_to_try
def read_coverage_config(
config_file: bool | str,
warn: Callable[[str], None],
**kwargs: TConfigValueIn,
) -> CoverageConfig:
"""Read the coverage.py configuration.
Arguments:
config_file: a boolean or string, see the `Coverage` class for the
tricky details.
warn: a function to issue warnings.
all others: keyword arguments from the `Coverage` class, used for
setting values in the configuration.
Returns:
config:
config is a CoverageConfig object read from the appropriate
configuration file.
"""
# Build the configuration from a number of sources:
# 1) defaults:
config = CoverageConfig()
# 2) from a file:
if config_file:
files_to_try = config_files_to_try(config_file)
for fname, our_file, specified_file in files_to_try:
config_read = config.from_file(fname, warn, our_file=our_file)
if config_read:
break
if specified_file:
raise ConfigError(f"Couldn't read {fname!r} as a config file")
# 3) from environment variables:
env_data_file = os.getenv("COVERAGE_FILE")
if env_data_file:
config.data_file = env_data_file
# $set_env.py: COVERAGE_DEBUG - Debug options: https://coverage.rtfd.io/cmd.html#debug
debugs = os.getenv("COVERAGE_DEBUG")
if debugs:
config.debug.extend(d.strip() for d in debugs.split(","))
# Read the COVERAGE_CORE environment variable for backward compatibility,
# and because we use it in the test suite to pick a specific core.
env_core = os.getenv("COVERAGE_CORE")
if env_core:
config.core = env_core
# 4) from constructor arguments:
config.from_args(**kwargs)
# 5) for our benchmark, force settings using a secret environment variable:
force_file = os.getenv("COVERAGE_FORCE_CONFIG")
if force_file:
config.from_file(force_file, warn, our_file=True)
# Once all the config has been collected, there's a little post-processing
# to do.
config.post_process()
return config
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/context.py 0000644 0001751 0001751 00000004600 15073731535 016703 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Determine contexts for coverage.py"""
from __future__ import annotations
from collections.abc import Sequence
from types import FrameType
from coverage.types import TShouldStartContextFn
def combine_context_switchers(
context_switchers: Sequence[TShouldStartContextFn],
) -> TShouldStartContextFn | None:
"""Create a single context switcher from multiple switchers.
`context_switchers` is a list of functions that take a frame as an
argument and return a string to use as the new context label.
Returns a function that composites `context_switchers` functions, or None
if `context_switchers` is an empty list.
When invoked, the combined switcher calls `context_switchers` one-by-one
until a string is returned. The combined switcher returns None if all
`context_switchers` return None.
"""
if not context_switchers:
return None
if len(context_switchers) == 1:
return context_switchers[0]
def should_start_context(frame: FrameType) -> str | None:
"""The combiner for multiple context switchers."""
for switcher in context_switchers:
new_context = switcher(frame)
if new_context is not None:
return new_context
return None
return should_start_context
def should_start_context_test_function(frame: FrameType) -> str | None:
"""Is this frame calling a test_* function?"""
co_name = frame.f_code.co_name
if co_name.startswith("test") or co_name == "runTest":
return qualname_from_frame(frame)
return None
def qualname_from_frame(frame: FrameType) -> str | None:
"""Get a qualified name for the code running in `frame`."""
co = frame.f_code
fname = co.co_name
method = None
if co.co_argcount and co.co_varnames[0] == "self":
self = frame.f_locals.get("self", None)
method = getattr(self, fname, None)
if method is None:
func = frame.f_globals.get(fname)
if func is None:
return None
return f"{func.__module__}.{fname}"
func = getattr(method, "__func__", None)
if func is None:
cls = self.__class__
return f"{cls.__module__}.{cls.__name__}.{fname}"
return f"{func.__module__}.{func.__qualname__}"
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/control.py 0000644 0001751 0001751 00000152521 15073731535 016705 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Central control stuff for coverage.py."""
from __future__ import annotations
import atexit
import collections
import contextlib
import functools
import os
import os.path
import platform
import signal
import sys
import threading
import time
import warnings
from collections.abc import Iterable, Iterator
from types import FrameType
from typing import IO, Any, Callable, cast
from coverage import env
from coverage.annotate import AnnotateReporter
from coverage.collector import Collector
from coverage.config import CoverageConfig, read_coverage_config
from coverage.context import combine_context_switchers, should_start_context_test_function
from coverage.core import CTRACER_FILE, Core
from coverage.data import CoverageData, combine_parallel_data
from coverage.debug import (
DebugControl,
NoDebugging,
relevant_environment_display,
short_stack,
write_formatted_info,
)
from coverage.disposition import disposition_debug_msg
from coverage.exceptions import ConfigError, CoverageException, CoverageWarning, PluginError
from coverage.files import PathAliases, abs_file, relative_filename, set_relative_directory
from coverage.html import HtmlReporter
from coverage.inorout import InOrOut
from coverage.jsonreport import JsonReporter
from coverage.lcovreport import LcovReporter
from coverage.misc import (
DefaultValue,
bool_or_none,
ensure_dir_for_file,
isolate_module,
join_regex,
)
from coverage.multiproc import patch_multiprocessing
from coverage.patch import apply_patches
from coverage.plugin import FileReporter
from coverage.plugin_support import Plugins, TCoverageInit
from coverage.python import PythonFileReporter
from coverage.report import SummaryReporter
from coverage.report_core import render_report
from coverage.results import Analysis, analysis_from_file_reporter
from coverage.types import (
FilePath,
TConfigSectionIn,
TConfigurable,
TConfigValueIn,
TConfigValueOut,
TFileDisposition,
TLineNo,
TMorf,
)
from coverage.version import __url__
from coverage.xmlreport import XmlReporter
os = isolate_module(os)
@contextlib.contextmanager
def override_config(cov: Coverage, **kwargs: TConfigValueIn) -> Iterator[None]:
"""Temporarily tweak the configuration of `cov`.
The arguments are applied to `cov.config` with the `from_args` method.
At the end of the with-statement, the old configuration is restored.
"""
original_config = cov.config
cov.config = cov.config.copy()
try:
cov.config.from_args(**kwargs)
yield
finally:
cov.config = original_config
DEFAULT_DATAFILE = DefaultValue("MISSING")
_DEFAULT_DATAFILE = DEFAULT_DATAFILE # Just in case, for backwards compatibility
CONFIG_DATA_PREFIX = ":data:"
class Coverage(TConfigurable):
"""Programmatic access to coverage.py.
To use::
from coverage import Coverage
cov = Coverage()
cov.start()
#.. call your code ..
cov.stop()
cov.html_report(directory="covhtml")
A context manager is available to do the same thing::
cov = Coverage()
with cov.collect():
#.. call your code ..
cov.html_report(directory="covhtml")
Note: in keeping with Python custom, names starting with underscore are
not part of the public API. They might stop working at any point. Please
limit yourself to documented methods to avoid problems.
Methods can raise any of the exceptions described in :ref:`api_exceptions`.
"""
# The stack of started Coverage instances.
_instances: list[Coverage] = []
@classmethod
def current(cls) -> Coverage | None:
"""Get the latest started `Coverage` instance, if any.
Returns: a `Coverage` instance, or None.
.. versionadded:: 5.0
"""
if cls._instances:
return cls._instances[-1]
else:
return None
def __init__( # pylint: disable=too-many-arguments
self,
data_file: FilePath | DefaultValue | None = DEFAULT_DATAFILE,
data_suffix: str | bool | None = None,
cover_pylib: bool | None = None,
auto_data: bool = False,
timid: bool | None = None,
branch: bool | None = None,
config_file: FilePath | bool = True,
source: Iterable[str] | None = None,
source_pkgs: Iterable[str] | None = None,
source_dirs: Iterable[str] | None = None,
omit: str | Iterable[str] | None = None,
include: str | Iterable[str] | None = None,
debug: Iterable[str] | None = None,
concurrency: str | Iterable[str] | None = None,
check_preimported: bool = False,
context: str | None = None,
messages: bool = False,
plugins: Iterable[Callable[..., None]] | None = None,
) -> None:
"""
Many of these arguments duplicate and override values that can be
provided in a configuration file. Parameters that are missing here
will use values from the config file.
`data_file` is the base name of the data file to use. The config value
defaults to ".coverage". None can be provided to prevent writing a data
file. `data_suffix` is appended (with a dot) to `data_file` to create
the final file name. If `data_suffix` is simply True, then a suffix is
created with the machine and process identity included.
`cover_pylib` is a boolean determining whether Python code installed
with the Python interpreter is measured. This includes the Python
standard library and any packages installed with the interpreter.
If `auto_data` is true, then any existing data file will be read when
coverage measurement starts, and data will be saved automatically when
measurement stops.
If `timid` is true, then a slower and simpler trace function will be
used. This is important for some environments where manipulation of
tracing functions breaks the faster trace function.
If `branch` is true, then branch coverage will be measured in addition
to the usual statement coverage.
`config_file` determines what configuration file to read:
* If it is ".coveragerc", it is interpreted as if it were True,
for backward compatibility.
* If it is a string, it is the name of the file to read. If the
file can't be read, it is an error.
* If it is True, then a few standard files names are tried
(".coveragerc", "setup.cfg", "tox.ini"). It is not an error for
these files to not be found.
* If it is False, then no configuration file is read.
`source` is a list of file paths or package names. Only code located
in the trees indicated by the file paths or package names will be
measured.
`source_pkgs` is a list of package names. It works the same as
`source`, but can be used to name packages where the name can also be
interpreted as a file path.
`source_dirs` is a list of file paths. It works the same as
`source`, but raises an error if the path doesn't exist, rather
than being treated as a package name.
`include` and `omit` are lists of file name patterns. Files that match
`include` will be measured, files that match `omit` will not. Each
will also accept a single string argument.
`debug` is a list of strings indicating what debugging information is
desired.
`concurrency` is a string indicating the concurrency library being used
in the measured code. Without this, coverage.py will get incorrect
results if these libraries are in use. Valid strings are "greenlet",
"eventlet", "gevent", "multiprocessing", or "thread" (the default).
This can also be a list of these strings.
If `check_preimported` is true, then when coverage is started, the
already-imported files will be checked to see if they should be
measured by coverage. Importing measured files before coverage is
started can mean that code is missed.
`context` is a string to use as the :ref:`static context
` label for collected data.
If `messages` is true, some messages will be printed to stdout
indicating what is happening.
If `plugins` are passed, they are an iterable of function objects
accepting a `reg` object to register plugins, as described in
:ref:`api_plugin`. When they are provided, they will override the
plugins found in the coverage configuration file.
.. versionadded:: 4.0
The `concurrency` parameter.
.. versionadded:: 4.2
The `concurrency` parameter can now be a list of strings.
.. versionadded:: 5.0
The `check_preimported` and `context` parameters.
.. versionadded:: 5.3
The `source_pkgs` parameter.
.. versionadded:: 6.0
The `messages` parameter.
.. versionadded:: 7.7
The `plugins` parameter.
.. versionadded:: 7.8
The `source_dirs` parameter.
"""
# Start self.config as a usable default configuration. It will soon be
# replaced with the real configuration.
self.config = CoverageConfig()
# data_file=None means no disk file at all. data_file missing means
# use the value from the config file.
self._no_disk = data_file is None
if isinstance(data_file, DefaultValue):
data_file = None
if data_file is not None:
data_file = os.fspath(data_file)
# This is injectable by tests.
self._debug_file: IO[str] | None = None
self._auto_load = self._auto_save = auto_data
self._data_suffix_specified = data_suffix
# Is it ok for no data to be collected?
self._warn_no_data = True
self._warn_unimported_source = True
self._warn_preimported_source = check_preimported
self._no_warn_slugs: set[str] = set()
self._messages = messages
# If we're invoked from a .pth file, we shouldn't try to make another one.
self._make_pth_file = True
# A record of all the warnings that have been issued.
self._warnings: list[str] = []
# Other instance attributes, set with placebos or placeholders.
# More useful objects will be created later.
self._debug: DebugControl = NoDebugging()
self._inorout: InOrOut | None = None
self._plugins: Plugins = Plugins()
self._plugin_override = cast(Iterable[TCoverageInit] | None, plugins)
self._data: CoverageData | None = None
self._data_to_close: list[CoverageData] = []
self._core: Core | None = None
self._collector: Collector | None = None
self._metacov = False
self._file_mapper: Callable[[str], str] = abs_file
self._data_suffix = self._run_suffix = None
self._exclude_re: dict[str, str] = {}
self._old_sigterm: Callable[[int, FrameType | None], Any] | None = None
# State machine variables:
# Have we initialized everything?
self._inited = False
self._inited_for_start = False
# Have we started collecting and not stopped it?
self._started = False
# Should we write the debug output?
self._should_write_debug = True
# Build our configuration from a number of sources.
if isinstance(config_file, str) and config_file.startswith(CONFIG_DATA_PREFIX):
self.config = CoverageConfig.deserialize(config_file[len(CONFIG_DATA_PREFIX) :])
else:
if not isinstance(config_file, bool):
config_file = os.fspath(config_file)
self.config = read_coverage_config(
config_file=config_file,
warn=self._warn,
data_file=data_file,
cover_pylib=cover_pylib,
timid=timid,
branch=branch,
parallel=bool_or_none(data_suffix),
source=source,
source_pkgs=source_pkgs,
source_dirs=source_dirs,
run_omit=omit,
run_include=include,
debug=debug,
report_omit=omit,
report_include=include,
concurrency=concurrency,
context=context,
)
# If we have subprocess measurement happening automatically, then we
# want any explicit creation of a Coverage object to mean, this process
# is already coverage-aware, so don't auto-measure it. By now, the
# auto-creation of a Coverage object has already happened. But we can
# find it and tell it not to save its data.
if not env.METACOV:
_prevent_sub_process_measurement()
def _init(self) -> None:
"""Set all the initial state.
This is called by the public methods to initialize state. This lets us
construct a :class:`Coverage` object, then tweak its state before this
function is called.
"""
if self._inited:
return
self._inited = True
# Create and configure the debugging controller.
self._debug = DebugControl(self.config.debug, self._debug_file, self.config.debug_file)
if self._debug.should("process"):
self._debug.write("Coverage._init")
if "multiprocessing" in (self.config.concurrency or ()):
# Multi-processing uses parallel for the subprocesses, so also use
# it for the main process.
self.config.parallel = True
# _exclude_re is a dict that maps exclusion list names to compiled regexes.
self._exclude_re = {}
set_relative_directory()
if self.config.relative_files:
self._file_mapper = relative_filename
# Load plugins
self._plugins = Plugins(self._debug)
if self._plugin_override:
self._plugins.load_from_callables(self._plugin_override)
else:
self._plugins.load_from_config(self.config.plugins, self.config)
# Run configuring plugins.
for plugin in self._plugins.configurers:
# We need an object with set_option and get_option. Either self or
# self.config will do. Choosing randomly stops people from doing
# other things with those objects, against the public API. Yes,
# this is a bit childish. :)
plugin.configure([self, self.config][int(time.time()) % 2])
def _post_init(self) -> None:
"""Stuff to do after everything is initialized."""
if self._should_write_debug:
self._should_write_debug = False
self._write_startup_debug()
# "[run] _crash" will raise an exception if the value is close by in
# the call stack, for testing error handling.
if self.config._crash and self.config._crash in short_stack():
raise RuntimeError(f"Crashing because called by {self.config._crash}")
def _write_startup_debug(self) -> None:
"""Write out debug info at startup if needed."""
wrote_any = False
with self._debug.without_callers():
if self._debug.should("config"):
config_info = self.config.debug_info()
write_formatted_info(self._debug.write, "config", config_info)
wrote_any = True
if self._debug.should("sys"):
write_formatted_info(self._debug.write, "sys", self.sys_info())
for plugin in self._plugins:
header = "sys: " + plugin._coverage_plugin_name
info = plugin.sys_info()
write_formatted_info(self._debug.write, header, info)
wrote_any = True
if self._debug.should("pybehave"):
write_formatted_info(self._debug.write, "pybehave", env.debug_info())
wrote_any = True
if wrote_any:
write_formatted_info(self._debug.write, "end", ())
def _should_trace(self, filename: str, frame: FrameType) -> TFileDisposition:
"""Decide whether to trace execution in `filename`.
Calls `_should_trace_internal`, and returns the FileDisposition.
"""
assert self._inorout is not None
disp = self._inorout.should_trace(filename, frame)
if self._debug.should("trace"):
self._debug.write(disposition_debug_msg(disp))
return disp
def _check_include_omit_etc(self, filename: str, frame: FrameType) -> bool:
"""Check a file name against the include/omit/etc, rules, verbosely.
Returns a boolean: True if the file should be traced, False if not.
"""
assert self._inorout is not None
reason = self._inorout.check_include_omit_etc(filename, frame)
if self._debug.should("trace"):
if not reason:
msg = f"Including {filename!r}"
else:
msg = f"Not including {filename!r}: {reason}"
self._debug.write(msg)
return not reason
def _warn(self, msg: str, slug: str | None = None, once: bool = False) -> None:
"""Use `msg` as a warning.
For warning suppression, use `slug` as the shorthand.
If `once` is true, only show this warning once (determined by the
slug.)
"""
if not self._no_warn_slugs:
self._no_warn_slugs = set(self.config.disable_warnings)
if slug in self._no_warn_slugs:
# Don't issue the warning
return
self._warnings.append(msg)
if slug:
msg = f"{msg} ({slug}); see {__url__}/messages.html#warning-{slug}"
if self._debug.should("pid"):
msg = f"[{os.getpid()}] {msg}"
warnings.warn(msg, category=CoverageWarning, stacklevel=2)
if once:
assert slug is not None
self._no_warn_slugs.add(slug)
def _message(self, msg: str) -> None:
"""Write a message to the user, if configured to do so."""
if self._messages:
print(msg)
def get_option(self, option_name: str) -> TConfigValueOut | None:
"""Get an option from the configuration.
`option_name` is a colon-separated string indicating the section and
option name. For example, the ``branch`` option in the ``[run]``
section of the config file would be indicated with `"run:branch"`.
Returns the value of the option. The type depends on the option
selected.
As a special case, an `option_name` of ``"paths"`` will return an
dictionary with the entire ``[paths]`` section value.
.. versionadded:: 4.0
"""
return self.config.get_option(option_name)
def set_option(self, option_name: str, value: TConfigValueIn | TConfigSectionIn) -> None:
"""Set an option in the configuration.
`option_name` is a colon-separated string indicating the section and
option name. For example, the ``branch`` option in the ``[run]``
section of the config file would be indicated with ``"run:branch"``.
`value` is the new value for the option. This should be an
appropriate Python value. For example, use True for booleans, not the
string ``"True"``.
As an example, calling:
.. code-block:: python
cov.set_option("run:branch", True)
has the same effect as this configuration file:
.. code-block:: ini
[run]
branch = True
As a special case, an `option_name` of ``"paths"`` will replace the
entire ``[paths]`` section. The value should be a dictionary.
.. versionadded:: 4.0
"""
self.config.set_option(option_name, value)
def load(self) -> None:
"""Load previously-collected coverage data from the data file."""
self._init()
if self._collector is not None:
self._collector.reset()
should_skip = self.config.parallel and not os.path.exists(self.config.data_file)
if not should_skip:
self._init_data(suffix=None)
self._post_init()
if not should_skip:
assert self._data is not None
self._data.read()
def _init_for_start(self) -> None:
"""Initialization for start()"""
# Construct the collector.
concurrency: list[str] = self.config.concurrency or []
if "multiprocessing" in concurrency:
if self.config.config_file is None:
raise ConfigError("multiprocessing requires a configuration file")
patch_multiprocessing(rcfile=self.config.config_file)
dycon = self.config.dynamic_context
if not dycon or dycon == "none":
context_switchers = []
elif dycon == "test_function":
context_switchers = [should_start_context_test_function]
else:
raise ConfigError(f"Don't understand dynamic_context setting: {dycon!r}")
context_switchers.extend(
plugin.dynamic_context for plugin in self._plugins.context_switchers
)
should_start_context = combine_context_switchers(context_switchers)
self._core = Core(
warn=self._warn,
config=self.config,
dynamic_contexts=(should_start_context is not None),
metacov=self._metacov,
)
self._collector = Collector(
core=self._core,
should_trace=self._should_trace,
check_include=self._check_include_omit_etc,
should_start_context=should_start_context,
file_mapper=self._file_mapper,
branch=self.config.branch,
warn=self._warn,
concurrency=concurrency,
)
suffix = self._data_suffix_specified
if suffix:
if not isinstance(suffix, str):
# if data_suffix=True, use .machinename.pid.random
suffix = True
elif self.config.parallel:
if suffix is None:
suffix = True
elif not isinstance(suffix, str):
suffix = bool(suffix)
else:
suffix = None
self._init_data(suffix)
assert self._data is not None
self._collector.use_data(self._data, self.config.context)
# Early warning if we aren't going to be able to support plugins.
if self._plugins.file_tracers and not self._core.supports_plugins:
self._warn(
"Plugin file tracers ({}) aren't supported with {}".format(
", ".join(
plugin._coverage_plugin_name for plugin in self._plugins.file_tracers
),
self._collector.tracer_name(),
),
)
for plugin in self._plugins.file_tracers:
plugin._coverage_enabled = False
# Create the file classifying substructure.
self._inorout = InOrOut(
config=self.config,
warn=self._warn,
debug=(self._debug if self._debug.should("trace") else None),
include_namespace_packages=self.config.include_namespace_packages,
)
self._inorout.plugins = self._plugins
self._inorout.disp_class = self._core.file_disposition_class
# It's useful to write debug info after initing for start.
self._should_write_debug = True
# Register our clean-up handlers.
atexit.register(self._atexit)
if self.config.sigterm:
is_main = (threading.current_thread() == threading.main_thread()) # fmt: skip
if is_main and not env.WINDOWS:
# The Python docs seem to imply that SIGTERM works uniformly even
# on Windows, but that's not my experience, and this agrees:
# https://stackoverflow.com/questions/35772001/x/35792192#35792192
self._old_sigterm = signal.signal( # type: ignore[assignment]
signal.SIGTERM,
self._on_sigterm,
)
def _init_data(self, suffix: str | bool | None) -> None:
"""Create a data file if we don't have one yet."""
if self._data is None:
# Create the data file. We do this at construction time so that the
# data file will be written into the directory where the process
# started rather than wherever the process eventually chdir'd to.
ensure_dir_for_file(self.config.data_file)
self._data = CoverageData(
basename=self.config.data_file,
suffix=suffix,
warn=self._warn,
debug=self._debug,
no_disk=self._no_disk,
)
self._data_to_close.append(self._data)
def start(self) -> None:
"""Start measuring code coverage.
Coverage measurement is only collected in functions called after
:meth:`start` is invoked. Statements in the same scope as
:meth:`start` won't be measured.
Once you invoke :meth:`start`, you must also call :meth:`stop`
eventually, or your process might not shut down cleanly.
The :meth:`collect` method is a context manager to handle both
starting and stopping collection.
"""
self._init()
if not self._inited_for_start:
self._inited_for_start = True
self._init_for_start()
self._post_init()
assert self._collector is not None
assert self._inorout is not None
# Issue warnings for possible problems.
self._inorout.warn_conflicting_settings()
# See if we think some code that would eventually be measured has
# already been imported.
if self._warn_preimported_source:
self._inorout.warn_already_imported_files()
if self._auto_load:
self.load()
apply_patches(self, self.config, self._debug, make_pth_file=self._make_pth_file)
self._collector.start()
self._started = True
self._instances.append(self)
def stop(self) -> None:
"""Stop measuring code coverage."""
if self._instances:
if self._instances[-1] is self:
self._instances.pop()
if self._started:
assert self._collector is not None
self._collector.stop()
self._started = False
@contextlib.contextmanager
def collect(self) -> Iterator[None]:
"""A context manager to start/stop coverage measurement collection.
.. versionadded:: 7.3
"""
self.start()
try:
yield
finally:
self.stop() # pragma: nested
def _atexit(self, event: str = "atexit") -> None:
"""Clean up on process shutdown."""
if self._debug.should("process"):
self._debug.write(f"{event}: pid: {os.getpid()}, instance: {self!r}")
if self._started:
self.stop()
if self._auto_save or event == "sigterm":
self.save()
for d in self._data_to_close:
d.close(force=True)
def _on_sigterm(self, signum_unused: int, frame_unused: FrameType | None) -> None:
"""A handler for signal.SIGTERM."""
self._atexit("sigterm")
# Statements after here won't be seen by metacov because we just wrote
# the data, and are about to kill the process.
signal.signal(signal.SIGTERM, self._old_sigterm) # pragma: not covered
os.kill(os.getpid(), signal.SIGTERM) # pragma: not covered
def erase(self) -> None:
"""Erase previously collected coverage data.
This removes the in-memory data collected in this session as well as
discarding the data file.
"""
self._init()
self._post_init()
if self._collector is not None:
self._collector.reset()
self._init_data(suffix=None)
assert self._data is not None
self._data.erase(parallel=self.config.parallel)
self._data = None
self._inited_for_start = False
def switch_context(self, new_context: str) -> None:
"""Switch to a new dynamic context.
`new_context` is a string to use as the :ref:`dynamic context
` label for collected data. If a :ref:`static
context ` is in use, the static and dynamic context
labels will be joined together with a pipe character.
Coverage collection must be started already.
.. versionadded:: 5.0
"""
if not self._started: # pragma: part started
raise CoverageException("Cannot switch context, coverage is not started")
assert self._collector is not None
if self._collector.should_start_context:
self._warn("Conflicting dynamic contexts", slug="dynamic-conflict", once=True)
self._collector.switch_context(new_context)
def clear_exclude(self, which: str = "exclude") -> None:
"""Clear the exclude list."""
self._init()
setattr(self.config, f"{which}_list", [])
self._exclude_regex_stale()
def exclude(self, regex: str, which: str = "exclude") -> None:
"""Exclude source lines from execution consideration.
A number of lists of regular expressions are maintained. Each list
selects lines that are treated differently during reporting.
`which` determines which list is modified. The "exclude" list selects
lines that are not considered executable at all. The "partial" list
indicates lines with branches that are not taken.
`regex` is a regular expression. The regex is added to the specified
list. If any of the regexes in the list is found in a line, the line
is marked for special treatment during reporting.
"""
self._init()
excl_list = getattr(self.config, f"{which}_list")
excl_list.append(regex)
self._exclude_regex_stale()
def _exclude_regex_stale(self) -> None:
"""Drop all the compiled exclusion regexes, a list was modified."""
self._exclude_re.clear()
def _exclude_regex(self, which: str) -> str:
"""Return a regex string for the given exclusion list."""
if which not in self._exclude_re:
excl_list = getattr(self.config, f"{which}_list")
self._exclude_re[which] = join_regex(excl_list)
return self._exclude_re[which]
def get_exclude_list(self, which: str = "exclude") -> list[str]:
"""Return a list of excluded regex strings.
`which` indicates which list is desired. See :meth:`exclude` for the
lists that are available, and their meaning.
"""
self._init()
return cast(list[str], getattr(self.config, f"{which}_list"))
def save(self) -> None:
"""Save the collected coverage data to the data file."""
data = self.get_data()
data.write()
def _make_aliases(self) -> PathAliases:
"""Create a PathAliases from our configuration."""
aliases = PathAliases(
debugfn=(self._debug.write if self._debug.should("pathmap") else None),
relative=self.config.relative_files,
)
for paths in self.config.paths.values():
result = paths[0]
for pattern in paths[1:]:
aliases.add(pattern, result)
return aliases
def combine(
self,
data_paths: Iterable[str] | None = None,
strict: bool = False,
keep: bool = False,
) -> None:
"""Combine together a number of similarly-named coverage data files.
All coverage data files whose name starts with `data_file` (from the
coverage() constructor) will be read, and combined together into the
current measurements.
`data_paths` is a list of files or directories from which data should
be combined. If no list is passed, then the data files from the
directory indicated by the current data file (probably the current
directory) will be combined.
If `strict` is true, then it is an error to attempt to combine when
there are no data files to combine.
If `keep` is true, then original input data files won't be deleted.
.. versionadded:: 4.0
The `data_paths` parameter.
.. versionadded:: 4.3
The `strict` parameter.
.. versionadded: 5.5
The `keep` parameter.
"""
self._init()
self._init_data(suffix=None)
self._post_init()
self.get_data()
assert self._data is not None
combine_parallel_data(
self._data,
aliases=self._make_aliases(),
data_paths=data_paths,
strict=strict,
keep=keep,
message=self._message,
)
def get_data(self) -> CoverageData:
"""Get the collected data.
Also warn about various problems collecting data.
Returns a :class:`coverage.CoverageData`, the collected coverage data.
.. versionadded:: 4.0
"""
self._init()
self._init_data(suffix=None)
self._post_init()
if self._collector is not None:
for plugin in self._plugins:
if not plugin._coverage_enabled:
self._collector.plugin_was_disabled(plugin)
if self._collector.flush_data():
self._post_save_work()
assert self._data is not None
return self._data
def _post_save_work(self) -> None:
"""After saving data, look for warnings, post-work, etc.
Warn about things that should have happened but didn't.
Look for un-executed files.
"""
assert self._data is not None
assert self._inorout is not None
# If there are still entries in the source_pkgs_unmatched list,
# then we never encountered those packages.
if self._warn_unimported_source:
self._inorout.warn_unimported_source()
# Find out if we got any data.
if not self._data and self._warn_no_data:
self._warn("No data was collected.", slug="no-data-collected")
# Touch all the files that could have executed, so that we can
# mark completely un-executed files as 0% covered.
file_paths = collections.defaultdict(list)
for file_path, plugin_name in self._inorout.find_possibly_unexecuted_files():
file_path = self._file_mapper(file_path)
file_paths[plugin_name].append(file_path)
for plugin_name, paths in file_paths.items():
self._data.touch_files(paths, plugin_name)
# Backward compatibility with version 1.
def analysis(self, morf: TMorf) -> tuple[str, list[TLineNo], list[TLineNo], str]:
"""Like `analysis2` but doesn't return excluded line numbers."""
f, s, _, m, mf = self.analysis2(morf)
return f, s, m, mf
def analysis2(
self,
morf: TMorf,
) -> tuple[str, list[TLineNo], list[TLineNo], list[TLineNo], str]:
"""Analyze a module.
`morf` is a module or a file name. It will be analyzed to determine
its coverage statistics. The return value is a 5-tuple:
* The file name for the module.
* A list of line numbers of executable statements.
* A list of line numbers of excluded statements.
* A list of line numbers of statements not run (missing from
execution).
* A readable formatted string of the missing line numbers.
The analysis uses the source file itself and the current measured
coverage data.
"""
analysis = self._analyze(morf)
return (
analysis.filename,
sorted(analysis.statements),
sorted(analysis.excluded),
sorted(analysis.missing),
analysis.missing_formatted(),
)
@functools.lru_cache(maxsize=1)
def _analyze(self, morf: TMorf) -> Analysis:
"""Analyze a module or file. Private for now."""
self._init()
self._post_init()
data = self.get_data()
file_reporter = self._get_file_reporter(morf)
filename = self._file_mapper(file_reporter.filename)
return analysis_from_file_reporter(data, self.config.precision, file_reporter, filename)
def branch_stats(self, morf: TMorf) -> dict[TLineNo, tuple[int, int]]:
"""Get branch statistics about a module.
`morf` is a module or a file name.
Returns a dict mapping line numbers to a tuple:
(total_exits, taken_exits).
.. versionadded:: 7.7
"""
analysis = self._analyze(morf)
return analysis.branch_stats()
@functools.lru_cache(maxsize=1)
def _get_file_reporter(self, morf: TMorf) -> FileReporter:
"""Get a FileReporter for a module or file name."""
assert self._data is not None
plugin = None
file_reporter: str | FileReporter = "python"
if isinstance(morf, str):
mapped_morf = self._file_mapper(morf)
plugin_name = self._data.file_tracer(mapped_morf)
if plugin_name:
plugin = self._plugins.get(plugin_name)
if plugin:
file_reporter = plugin.file_reporter(mapped_morf)
if file_reporter is None:
raise PluginError(
"Plugin {!r} did not provide a file reporter for {!r}.".format(
plugin._coverage_plugin_name,
morf,
),
)
if file_reporter == "python":
file_reporter = PythonFileReporter(morf, self)
assert isinstance(file_reporter, FileReporter)
return file_reporter
def _get_file_reporters(
self,
morfs: Iterable[TMorf] | None = None,
) -> list[tuple[FileReporter, TMorf]]:
"""Get FileReporters for a list of modules or file names.
For each module or file name in `morfs`, find a FileReporter. Return
a list pairing FileReporters with the morfs.
If `morfs` is a single module or file name, this returns a list of one
FileReporter. If `morfs` is empty or None, then the list of all files
measured is used to find the FileReporters.
"""
assert self._data is not None
if not morfs:
morfs = self._data.measured_files()
# Be sure we have a collection.
if not isinstance(morfs, (list, tuple, set)):
morfs = [morfs] # type: ignore[list-item]
morfs = sorted(morfs, key=lambda m: m if isinstance(m, str) else m.__name__)
return [(self._get_file_reporter(morf), morf) for morf in morfs]
def _prepare_data_for_reporting(self) -> None:
"""Re-map data before reporting, to get implicit "combine" behavior."""
if self.config.paths:
mapped_data = CoverageData(warn=self._warn, debug=self._debug, no_disk=True)
if self._data is not None:
mapped_data.update(self._data, map_path=self._make_aliases().map)
self._data = mapped_data
self._data_to_close.append(mapped_data)
def report(
self,
morfs: Iterable[TMorf] | None = None,
show_missing: bool | None = None,
ignore_errors: bool | None = None,
file: IO[str] | None = None,
omit: str | list[str] | None = None,
include: str | list[str] | None = None,
skip_covered: bool | None = None,
contexts: list[str] | None = None,
skip_empty: bool | None = None,
precision: int | None = None,
sort: str | None = None,
output_format: str | None = None,
) -> float:
"""Write a textual summary report to `file`.
Each module in `morfs` is listed, with counts of statements, executed
statements, missing statements, and a list of lines missed.
If `show_missing` is true, then details of which lines or branches are
missing will be included in the report. If `ignore_errors` is true,
then a failure while reporting a single file will not stop the entire
report.
`file` is a file-like object, suitable for writing.
`output_format` determines the format, either "text" (the default),
"markdown", or "total".
`include` is a list of file name patterns. Files that match will be
included in the report. Files matching `omit` will not be included in
the report.
If `skip_covered` is true, don't report on files with 100% coverage.
If `skip_empty` is true, don't report on empty files (those that have
no statements).
`contexts` is a list of regular expression strings. Only data from
:ref:`dynamic contexts ` that match one of those
expressions (using :func:`re.search `) will be
included in the report.
`precision` is the number of digits to display after the decimal
point for percentages.
All of the arguments default to the settings read from the
:ref:`configuration file `.
Returns a float, the total percentage covered.
.. versionadded:: 4.0
The `skip_covered` parameter.
.. versionadded:: 5.0
The `contexts` and `skip_empty` parameters.
.. versionadded:: 5.2
The `precision` parameter.
.. versionadded:: 7.0
The `format` parameter.
"""
self._prepare_data_for_reporting()
with override_config(
self,
ignore_errors=ignore_errors,
report_omit=omit,
report_include=include,
show_missing=show_missing,
skip_covered=skip_covered,
report_contexts=contexts,
skip_empty=skip_empty,
precision=precision,
sort=sort,
format=output_format,
):
reporter = SummaryReporter(self)
return reporter.report(morfs, outfile=file)
def annotate(
self,
morfs: Iterable[TMorf] | None = None,
directory: str | None = None,
ignore_errors: bool | None = None,
omit: str | list[str] | None = None,
include: str | list[str] | None = None,
contexts: list[str] | None = None,
) -> None:
"""Annotate a list of modules.
Each module in `morfs` is annotated. The source is written to a new
file, named with a ",cover" suffix, with each line prefixed with a
marker to indicate the coverage of the line. Covered lines have ">",
excluded lines have "-", and missing lines have "!".
See :meth:`report` for other arguments.
"""
self._prepare_data_for_reporting()
with override_config(
self,
ignore_errors=ignore_errors,
report_omit=omit,
report_include=include,
report_contexts=contexts,
):
reporter = AnnotateReporter(self)
reporter.report(morfs, directory=directory)
def html_report(
self,
morfs: Iterable[TMorf] | None = None,
directory: str | None = None,
ignore_errors: bool | None = None,
omit: str | list[str] | None = None,
include: str | list[str] | None = None,
extra_css: str | None = None,
title: str | None = None,
skip_covered: bool | None = None,
show_contexts: bool | None = None,
contexts: list[str] | None = None,
skip_empty: bool | None = None,
precision: int | None = None,
) -> float:
"""Generate an HTML report.
The HTML is written to `directory`. The file "index.html" is the
overview starting point, with links to more detailed pages for
individual modules.
`extra_css` is a path to a file of other CSS to apply on the page.
It will be copied into the HTML directory.
`title` is a text string (not HTML) to use as the title of the HTML
report.
See :meth:`report` for other arguments.
Returns a float, the total percentage covered.
.. note::
The HTML report files are generated incrementally based on the
source files and coverage results. If you modify the report files,
the changes will not be considered. You should be careful about
changing the files in the report folder.
"""
self._prepare_data_for_reporting()
with override_config(
self,
ignore_errors=ignore_errors,
report_omit=omit,
report_include=include,
html_dir=directory,
extra_css=extra_css,
html_title=title,
html_skip_covered=skip_covered,
show_contexts=show_contexts,
report_contexts=contexts,
html_skip_empty=skip_empty,
precision=precision,
):
reporter = HtmlReporter(self)
return reporter.report(morfs)
def xml_report(
self,
morfs: Iterable[TMorf] | None = None,
outfile: str | None = None,
ignore_errors: bool | None = None,
omit: str | list[str] | None = None,
include: str | list[str] | None = None,
contexts: list[str] | None = None,
skip_empty: bool | None = None,
) -> float:
"""Generate an XML report of coverage results.
The report is compatible with Cobertura reports.
Each module in `morfs` is included in the report. `outfile` is the
path to write the file to, "-" will write to stdout.
See :meth:`report` for other arguments.
Returns a float, the total percentage covered.
"""
self._prepare_data_for_reporting()
with override_config(
self,
ignore_errors=ignore_errors,
report_omit=omit,
report_include=include,
xml_output=outfile,
report_contexts=contexts,
skip_empty=skip_empty,
):
return render_report(self.config.xml_output, XmlReporter(self), morfs, self._message)
def json_report(
self,
morfs: Iterable[TMorf] | None = None,
outfile: str | None = None,
ignore_errors: bool | None = None,
omit: str | list[str] | None = None,
include: str | list[str] | None = None,
contexts: list[str] | None = None,
pretty_print: bool | None = None,
show_contexts: bool | None = None,
) -> float:
"""Generate a JSON report of coverage results.
Each module in `morfs` is included in the report. `outfile` is the
path to write the file to, "-" will write to stdout.
`pretty_print` is a boolean, whether to pretty-print the JSON output or not.
See :meth:`report` for other arguments.
Returns a float, the total percentage covered.
.. versionadded:: 5.0
"""
self._prepare_data_for_reporting()
with override_config(
self,
ignore_errors=ignore_errors,
report_omit=omit,
report_include=include,
json_output=outfile,
report_contexts=contexts,
json_pretty_print=pretty_print,
json_show_contexts=show_contexts,
):
return render_report(self.config.json_output, JsonReporter(self), morfs, self._message)
def lcov_report(
self,
morfs: Iterable[TMorf] | None = None,
outfile: str | None = None,
ignore_errors: bool | None = None,
omit: str | list[str] | None = None,
include: str | list[str] | None = None,
contexts: list[str] | None = None,
) -> float:
"""Generate an LCOV report of coverage results.
Each module in `morfs` is included in the report. `outfile` is the
path to write the file to, "-" will write to stdout.
See :meth:`report` for other arguments.
.. versionadded:: 6.3
"""
self._prepare_data_for_reporting()
with override_config(
self,
ignore_errors=ignore_errors,
report_omit=omit,
report_include=include,
lcov_output=outfile,
report_contexts=contexts,
):
return render_report(self.config.lcov_output, LcovReporter(self), morfs, self._message)
def sys_info(self) -> Iterable[tuple[str, Any]]:
"""Return a list of (key, value) pairs showing internal information."""
import coverage as covmod
self._init()
self._post_init()
def plugin_info(plugins: list[Any]) -> list[str]:
"""Make an entry for the sys_info from a list of plug-ins."""
entries = []
for plugin in plugins:
entry = plugin._coverage_plugin_name
if not plugin._coverage_enabled:
entry += " (disabled)"
entries.append(entry)
return entries
info = [
("coverage_version", covmod.__version__),
("coverage_module", covmod.__file__),
("core", self._collector.tracer_name() if self._collector is not None else "-none-"),
("CTracer", f"available from {CTRACER_FILE}" if CTRACER_FILE else "unavailable"),
("plugins.file_tracers", plugin_info(self._plugins.file_tracers)),
("plugins.configurers", plugin_info(self._plugins.configurers)),
("plugins.context_switchers", plugin_info(self._plugins.context_switchers)),
("configs_attempted", self.config.config_files_attempted),
("configs_read", self.config.config_files_read),
("config_file", self.config.config_file),
(
"config_contents",
repr(self.config._config_contents) if self.config._config_contents else "-none-",
),
("data_file", self._data.data_filename() if self._data is not None else "-none-"),
("python", sys.version.replace("\n", "")),
("platform", platform.platform()),
("implementation", platform.python_implementation()),
("build", platform.python_build()),
("gil_enabled", getattr(sys, "_is_gil_enabled", lambda: True)()),
("executable", sys.executable),
("def_encoding", sys.getdefaultencoding()),
("fs_encoding", sys.getfilesystemencoding()),
("pid", os.getpid()),
("cwd", os.getcwd()),
("path", sys.path),
("environment", [f"{k} = {v}" for k, v in relevant_environment_display(os.environ)]),
("command_line", " ".join(getattr(sys, "argv", ["-none-"]))),
]
if self._inorout is not None:
info.extend(self._inorout.sys_info())
info.extend(CoverageData.sys_info())
return info
# Mega debugging...
# $set_env.py: COVERAGE_DEBUG_CALLS - Lots and lots of output about calls to Coverage.
if int(os.getenv("COVERAGE_DEBUG_CALLS", 0)): # pragma: debugging
from coverage.debug import decorate_methods, show_calls
Coverage = decorate_methods( # type: ignore[misc]
show_calls(show_args=True),
butnot=["get_data"],
)(Coverage)
def process_startup(*, force: bool = False) -> Coverage | None:
"""Call this at Python start-up to perhaps measure coverage.
If the environment variable COVERAGE_PROCESS_START is defined, coverage
measurement is started. The value of the variable is the config file
to use.
For details, see https://coverage.readthedocs.io/en/latest/subprocess.html.
Returns the :class:`Coverage` instance that was started, or None if it was
not started by this call.
"""
config_data = os.getenv("COVERAGE_PROCESS_CONFIG")
cps = os.getenv("COVERAGE_PROCESS_START")
if config_data is not None:
config_file = CONFIG_DATA_PREFIX + config_data
elif cps is not None:
config_file = cps
else:
# No request for coverage, nothing to do.
return None
# This function can be called more than once in a process. This happens
# because some virtualenv configurations make the same directory visible
# twice in sys.path. This means that the .pth file will be found twice,
# and executed twice, executing this function twice. We set a global
# flag (an attribute on this function) to indicate that coverage.py has
# already been started, so we can avoid doing it twice.
#
# https://github.com/nedbat/coveragepy/issues/340 has more details.
if not force and hasattr(process_startup, "coverage"):
# We've annotated this function before, so we must have already
# auto-started coverage.py in this process. Nothing to do.
return None
cov = Coverage(config_file=config_file)
process_startup.coverage = cov # type: ignore[attr-defined]
cov._warn_no_data = False
cov._warn_unimported_source = False
cov._warn_preimported_source = False
cov._auto_save = True
cov._make_pth_file = False
cov.start()
return cov
def _after_fork_in_child() -> None:
"""Used by patch=fork in the child process to restart coverage."""
if cov := Coverage.current():
cov.stop()
process_startup(force=True)
def _prevent_sub_process_measurement() -> None:
"""Stop any subprocess auto-measurement from writing data."""
auto_created_coverage = getattr(process_startup, "coverage", None)
if auto_created_coverage is not None:
auto_created_coverage._auto_save = False
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/core.py 0000644 0001751 0001751 00000010407 15073731535 016151 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Management of core choices."""
from __future__ import annotations
import os
import sys
from typing import Any
from coverage import env
from coverage.config import CoverageConfig
from coverage.disposition import FileDisposition
from coverage.exceptions import ConfigError
from coverage.misc import isolate_module
from coverage.pytracer import PyTracer
from coverage.sysmon import SysMonitor
from coverage.types import TFileDisposition, Tracer, TWarnFn
os = isolate_module(os)
IMPORT_ERROR: str = ""
try:
# Use the C extension code when we can, for speed.
import coverage.tracer
CTRACER_FILE: str | None = getattr(coverage.tracer, "__file__", "unknown")
except ImportError as imp_err:
# Couldn't import the C extension, maybe it isn't built.
# We still need to check the environment variable directly here,
# as this code runs before configuration is loaded.
if os.getenv("COVERAGE_CORE") == "ctrace": # pragma: part covered
# During testing, we use the COVERAGE_CORE environment variable
# to indicate that we've fiddled with the environment to test this
# fallback code. If we thought we had a C tracer, but couldn't import
# it, then exit quickly and clearly instead of dribbling confusing
# errors. I'm using sys.exit here instead of an exception because an
# exception here causes all sorts of other noise in unittest.
sys.stderr.write("*** COVERAGE_CORE is 'ctrace' but can't import CTracer!\n")
sys.exit(1)
IMPORT_ERROR = str(imp_err)
CTRACER_FILE = None
class Core:
"""Information about the central technology enabling execution measurement."""
tracer_class: type[Tracer]
tracer_kwargs: dict[str, Any]
file_disposition_class: type[TFileDisposition]
supports_plugins: bool
packed_arcs: bool
systrace: bool
def __init__(
self,
warn: TWarnFn,
config: CoverageConfig,
dynamic_contexts: bool,
metacov: bool,
) -> None:
# Check the conditions that preclude us from using sys.monitoring.
reason_no_sysmon = ""
if not env.PYBEHAVIOR.pep669:
reason_no_sysmon = "isn't available in this version"
elif config.branch and not env.PYBEHAVIOR.branch_right_left:
reason_no_sysmon = "can't measure branches in this version"
elif dynamic_contexts:
reason_no_sysmon = "doesn't yet support dynamic contexts"
core_name: str | None = None
if config.timid:
core_name = "pytrace"
if core_name is None:
core_name = config.core
if core_name == "sysmon" and reason_no_sysmon:
warn(f"sys.monitoring {reason_no_sysmon}, using default core", slug="no-sysmon")
core_name = None
if core_name is None:
if env.SYSMON_DEFAULT and not reason_no_sysmon:
core_name = "sysmon"
else:
core_name = "ctrace"
if core_name == "ctrace":
if not CTRACER_FILE:
if IMPORT_ERROR and env.SHIPPING_WHEELS:
warn(f"Couldn't import C tracer: {IMPORT_ERROR}", slug="no-ctracer", once=True)
core_name = "pytrace"
self.tracer_kwargs = {}
if core_name == "sysmon":
self.tracer_class = SysMonitor
self.tracer_kwargs["tool_id"] = 3 if metacov else 1
self.file_disposition_class = FileDisposition
self.supports_plugins = False
self.packed_arcs = False
self.systrace = False
elif core_name == "ctrace":
self.tracer_class = coverage.tracer.CTracer
self.file_disposition_class = coverage.tracer.CFileDisposition
self.supports_plugins = True
self.packed_arcs = True
self.systrace = True
elif core_name == "pytrace":
self.tracer_class = PyTracer
self.file_disposition_class = FileDisposition
self.supports_plugins = False
self.packed_arcs = False
self.systrace = True
else:
raise ConfigError(f"Unknown core value: {core_name!r}")
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9421895
coverage-7.11.0/coverage/ctracer/ 0000755 0001751 0001751 00000000000 15073731560 016266 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/ctracer/datastack.c 0000644 0001751 0001751 00000002627 15073731535 020402 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
#include "util.h"
#include "datastack.h"
#define STACK_DELTA 20
int
DataStack_init(Stats *pstats, DataStack *pdata_stack)
{
pdata_stack->depth = -1;
pdata_stack->stack = NULL;
pdata_stack->alloc = 0;
return RET_OK;
}
void
DataStack_dealloc(Stats *pstats, DataStack *pdata_stack)
{
int i;
for (i = 0; i < pdata_stack->alloc; i++) {
Py_XDECREF(pdata_stack->stack[i].file_data);
}
PyMem_Free(pdata_stack->stack);
}
int
DataStack_grow(Stats *pstats, DataStack *pdata_stack)
{
pdata_stack->depth++;
if (pdata_stack->depth >= pdata_stack->alloc) {
/* We've outgrown our data_stack array: make it bigger. */
int bigger = pdata_stack->alloc + STACK_DELTA;
DataStackEntry * bigger_data_stack = PyMem_Realloc(pdata_stack->stack, bigger * sizeof(DataStackEntry));
STATS( pstats->stack_reallocs++; )
if (bigger_data_stack == NULL) {
PyErr_NoMemory();
pdata_stack->depth--;
return RET_ERROR;
}
/* Zero the new entries. */
memset(bigger_data_stack + pdata_stack->alloc, 0, STACK_DELTA * sizeof(DataStackEntry));
pdata_stack->stack = bigger_data_stack;
pdata_stack->alloc = bigger;
}
return RET_OK;
}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/ctracer/datastack.h 0000644 0001751 0001751 00000003005 15073731535 020376 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
#ifndef _COVERAGE_DATASTACK_H
#define _COVERAGE_DATASTACK_H
#include "util.h"
#include "stats.h"
/* An entry on the data stack. For each call frame, we need to record all
* the information needed for CTracer_handle_line to operate as quickly as
* possible.
*/
typedef struct DataStackEntry {
/* The current file_data set. Owned. */
PyObject * file_data;
/* The disposition object for this frame. A borrowed instance of CFileDisposition. */
PyObject * disposition;
/* The FileTracer handling this frame, or None if it's Python. Borrowed. */
PyObject * file_tracer;
/* The line number of the last line recorded, for tracing arcs.
-1 means there was no previous line, as when entering a code object.
*/
int last_line;
BOOL started_context;
} DataStackEntry;
/* A data stack is a dynamically allocated vector of DataStackEntry's. */
typedef struct DataStack {
int depth; /* The index of the last-used entry in stack. */
int alloc; /* number of entries allocated at stack. */
/* The file data at each level, or NULL if not recording. */
DataStackEntry * stack;
} DataStack;
int DataStack_init(Stats * pstats, DataStack *pdata_stack);
void DataStack_dealloc(Stats * pstats, DataStack *pdata_stack);
int DataStack_grow(Stats * pstats, DataStack *pdata_stack);
#endif /* _COVERAGE_DATASTACK_H */
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/ctracer/filedisp.c 0000644 0001751 0001751 00000006300 15073731535 020232 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
#include "util.h"
#include "filedisp.h"
void
CFileDisposition_dealloc(CFileDisposition *self)
{
Py_XDECREF(self->original_filename);
Py_XDECREF(self->canonical_filename);
Py_XDECREF(self->source_filename);
Py_XDECREF(self->trace);
Py_XDECREF(self->reason);
Py_XDECREF(self->file_tracer);
Py_XDECREF(self->has_dynamic_filename);
}
static PyMemberDef
CFileDisposition_members[] = {
{ "original_filename", T_OBJECT, offsetof(CFileDisposition, original_filename), 0,
PyDoc_STR("") },
{ "canonical_filename", T_OBJECT, offsetof(CFileDisposition, canonical_filename), 0,
PyDoc_STR("") },
{ "source_filename", T_OBJECT, offsetof(CFileDisposition, source_filename), 0,
PyDoc_STR("") },
{ "trace", T_OBJECT, offsetof(CFileDisposition, trace), 0,
PyDoc_STR("") },
{ "reason", T_OBJECT, offsetof(CFileDisposition, reason), 0,
PyDoc_STR("") },
{ "file_tracer", T_OBJECT, offsetof(CFileDisposition, file_tracer), 0,
PyDoc_STR("") },
{ "has_dynamic_filename", T_OBJECT, offsetof(CFileDisposition, has_dynamic_filename), 0,
PyDoc_STR("") },
{ NULL }
};
PyTypeObject
CFileDispositionType = {
PyVarObject_HEAD_INIT(NULL, 0)
"coverage.CFileDispositionType", /*tp_name*/
sizeof(CFileDisposition), /*tp_basicsize*/
0, /*tp_itemsize*/
(destructor)CFileDisposition_dealloc, /*tp_dealloc*/
0, /*tp_print*/
0, /*tp_getattr*/
0, /*tp_setattr*/
0, /*tp_compare*/
0, /*tp_repr*/
0, /*tp_as_number*/
0, /*tp_as_sequence*/
0, /*tp_as_mapping*/
0, /*tp_hash */
0, /*tp_call*/
0, /*tp_str*/
0, /*tp_getattro*/
0, /*tp_setattro*/
0, /*tp_as_buffer*/
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
"CFileDisposition objects", /* tp_doc */
0, /* tp_traverse */
0, /* tp_clear */
0, /* tp_richcompare */
0, /* tp_weaklistoffset */
0, /* tp_iter */
0, /* tp_iternext */
0, /* tp_methods */
CFileDisposition_members, /* tp_members */
0, /* tp_getset */
0, /* tp_base */
0, /* tp_dict */
0, /* tp_descr_get */
0, /* tp_descr_set */
0, /* tp_dictoffset */
0, /* tp_init */
0, /* tp_alloc */
0, /* tp_new */
};
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/ctracer/filedisp.h 0000644 0001751 0001751 00000001256 15073731535 020244 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
#ifndef _COVERAGE_FILEDISP_H
#define _COVERAGE_FILEDISP_H
#include "util.h"
#include "structmember.h"
typedef struct CFileDisposition {
PyObject_HEAD
PyObject * original_filename;
PyObject * canonical_filename;
PyObject * source_filename;
PyObject * trace;
PyObject * reason;
PyObject * file_tracer;
PyObject * has_dynamic_filename;
} CFileDisposition;
void CFileDisposition_dealloc(CFileDisposition *self);
extern PyTypeObject CFileDispositionType;
#endif /* _COVERAGE_FILEDISP_H */
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/ctracer/module.c 0000644 0001751 0001751 00000003615 15073731535 017726 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
#include "util.h"
#include "tracer.h"
#include "filedisp.h"
/* Module definition */
#define MODULE_DOC PyDoc_STR("Fast coverage tracer.")
static BOOL module_inited = FALSE;
static int
tracer_exec(PyObject *mod)
{
if (module_inited) {
return 0;
}
if (CTracer_intern_strings() < 0) {
return -1;
}
/* Initialize CTracer */
CTracerType.tp_new = PyType_GenericNew;
if (PyType_Ready(&CTracerType) < 0) {
return -1;
}
Py_INCREF(&CTracerType);
if (PyModule_AddObject(mod, "CTracer", (PyObject *)&CTracerType) < 0) {
Py_DECREF(&CTracerType);
return -1;
}
/* Initialize CFileDisposition */
CFileDispositionType.tp_new = PyType_GenericNew;
if (PyType_Ready(&CFileDispositionType) < 0) {
Py_DECREF(&CTracerType);
return -1;
}
Py_INCREF(&CFileDispositionType);
if (PyModule_AddObject(mod, "CFileDisposition", (PyObject *)&CFileDispositionType) < 0) {
Py_DECREF(&CTracerType);
Py_DECREF(&CFileDispositionType);
return -1;
}
module_inited = TRUE;
return 0;
}
static PyModuleDef_Slot tracer_slots[] = {
{Py_mod_exec, tracer_exec},
#if PY_VERSION_HEX >= 0x030c00f0 // Python 3.12+
{Py_mod_multiple_interpreters, Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},
#endif
#if PY_VERSION_HEX >= 0x030d00f0 // Python 3.13+
// signal that this module supports running without an active GIL
{Py_mod_gil, Py_MOD_GIL_NOT_USED},
#endif
{0, NULL}
};
static PyModuleDef moduledef = {
.m_base = PyModuleDef_HEAD_INIT,
.m_name = "coverage.tracer",
.m_doc = MODULE_DOC,
.m_size = 0,
.m_slots = tracer_slots,
};
PyMODINIT_FUNC
PyInit_tracer(void)
{
return PyModuleDef_Init(&moduledef);
}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/ctracer/stats.h 0000644 0001751 0001751 00000001306 15073731535 017577 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
#ifndef _COVERAGE_STATS_H
#define _COVERAGE_STATS_H
#include "util.h"
#if COLLECT_STATS
#define STATS(x) x
#else
#define STATS(x)
#endif
typedef struct Stats {
unsigned int calls; /* Need at least one member, but the rest only if needed. */
#if COLLECT_STATS
unsigned int lines;
unsigned int returns;
unsigned int others;
unsigned int files;
unsigned int stack_reallocs;
unsigned int errors;
unsigned int pycalls;
unsigned int start_context_calls;
#endif
} Stats;
#endif /* _COVERAGE_STATS_H */
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/ctracer/tracer.c 0000644 0001751 0001751 00000105611 15073731535 017720 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
/* C-based Tracer for coverage.py. */
#include "util.h"
#include "datastack.h"
#include "filedisp.h"
#include "tracer.h"
/* Python C API helpers. */
static int
pyint_as_int(PyObject * pyint, int *pint)
{
int the_int = (int)PyLong_AsLong(pyint);
if (the_int == -1 && PyErr_Occurred()) {
return RET_ERROR;
}
*pint = the_int;
return RET_OK;
}
/* Interned strings to speed GetAttr etc. */
static PyObject *str__coverage_plugin;
static PyObject *str__coverage_plugin_name;
static PyObject *str_dynamic_source_filename;
static PyObject *str_line_number_range;
int
CTracer_intern_strings(void)
{
int ret = RET_ERROR;
#define INTERN_STRING(v, s) \
v = PyUnicode_InternFromString(s); \
if (v == NULL) { \
goto error; \
}
INTERN_STRING(str__coverage_plugin, "_coverage_plugin")
INTERN_STRING(str__coverage_plugin_name, "_coverage_plugin_name")
INTERN_STRING(str_dynamic_source_filename, "dynamic_source_filename")
INTERN_STRING(str_line_number_range, "line_number_range")
ret = RET_OK;
error:
return ret;
}
static void CTracer_disable_plugin(CTracer *self, PyObject * disposition);
static int
CTracer_init(CTracer *self, PyObject *args_unused, PyObject *kwds_unused)
{
int ret = RET_ERROR;
if (DataStack_init(&self->stats, &self->data_stack) < 0) {
goto error;
}
self->pdata_stack = &self->data_stack;
self->context = Py_None;
Py_INCREF(self->context);
ret = RET_OK;
goto ok;
error:
STATS( self->stats.errors++; )
ok:
return ret;
}
static void
CTracer_dealloc(CTracer *self)
{
int i;
if (self->started) {
PyEval_SetTrace(NULL, NULL);
}
Py_XDECREF(self->should_trace);
Py_XDECREF(self->check_include);
Py_XDECREF(self->warn);
Py_XDECREF(self->concur_id_func);
Py_XDECREF(self->data);
Py_XDECREF(self->file_tracers);
Py_XDECREF(self->should_trace_cache);
Py_XDECREF(self->should_start_context);
Py_XDECREF(self->switch_context);
Py_XDECREF(self->lock_data);
Py_XDECREF(self->unlock_data);
Py_XDECREF(self->context);
Py_XDECREF(self->disable_plugin);
DataStack_dealloc(&self->stats, &self->data_stack);
if (self->data_stacks) {
for (i = 0; i < self->data_stacks_used; i++) {
DataStack_dealloc(&self->stats, self->data_stacks + i);
}
PyMem_Free(self->data_stacks);
}
Py_XDECREF(self->data_stack_index);
Py_TYPE(self)->tp_free((PyObject*)self);
}
#if TRACE_LOG
/* Set debugging constants: a file substring and line number to start logging. */
static const char * start_file = "badasync.py";
static int start_line = 1;
static const char *
indent(int n)
{
static const char * spaces =
" "
" "
" "
" "
;
return spaces + strlen(spaces) - n*2;
}
static BOOL logging = FALSE;
static void
CTracer_showlog(CTracer * self, int lineno, PyObject * filename, const char * msg)
{
if (logging) {
int depth = self->pdata_stack->depth;
printf("%x: %s%3d ", (int)self, indent(depth), depth);
if (lineno) {
printf("%4d", lineno);
}
else {
printf(" ");
}
if (filename) {
PyObject *ascii = PyUnicode_AsASCIIString(filename);
printf(" %s", PyBytes_AS_STRING(ascii));
Py_DECREF(ascii);
}
if (msg) {
printf(" %s", msg);
}
printf("\n");
}
}
#define SHOWLOG(l,f,m) CTracer_showlog(self,l,f,m)
#else
#define SHOWLOG(l,f,m)
#endif /* TRACE_LOG */
#if WHAT_LOG
static const char * what_sym[] = {"CALL", "EXC ", "LINE", "RET "};
#endif
/* Record a pair of integers in self->pcur_entry->file_data. */
static int
CTracer_record_pair(CTracer *self, int l1, int l2)
{
int ret = RET_ERROR;
PyObject * packed_obj = NULL;
uint64 packed = 0;
// Conceptually, data is a set of tuples (l1, l2), but that literally
// making a set of tuples would require us to construct a tuple just to
// see if we'd already recorded an arc. On many-times-executed code,
// that would mean we construct a tuple, find the tuple is already in the
// set, then discard the tuple. We can avoid that overhead by packing
// the two line numbers into one integer instead.
// See collector.py:flush_data for the Python code that unpacks this.
if (l1 < 0) {
packed |= (1LL << 40);
l1 = -l1;
}
if (l2 < 0) {
packed |= (1LL << 41);
l2 = -l2;
}
packed |= (((uint64)l2) << 20) + (uint64)l1;
packed_obj = PyLong_FromUnsignedLongLong(packed);
if (packed_obj == NULL) {
goto error;
}
if (PySet_Add(self->pcur_entry->file_data, packed_obj) < 0) {
goto error;
}
ret = RET_OK;
error:
Py_XDECREF(packed_obj);
return ret;
}
/* Set self->pdata_stack to the proper data_stack to use. */
static int
CTracer_set_pdata_stack(CTracer *self)
{
int ret = RET_ERROR;
PyObject * co_obj = NULL;
PyObject * stack_index = NULL;
if (self->concur_id_func != Py_None) {
int the_index = 0;
if (self->data_stack_index == NULL) {
PyObject * weakref = NULL;
weakref = PyImport_ImportModule("weakref");
if (weakref == NULL) {
goto error;
}
STATS( self->stats.pycalls++; )
self->data_stack_index = PyObject_CallMethod(weakref, "WeakKeyDictionary", NULL);
Py_XDECREF(weakref);
if (self->data_stack_index == NULL) {
goto error;
}
}
STATS( self->stats.pycalls++; )
co_obj = PyObject_CallObject(self->concur_id_func, NULL);
if (co_obj == NULL) {
goto error;
}
stack_index = PyObject_GetItem(self->data_stack_index, co_obj);
if (stack_index == NULL) {
/* PyObject_GetItem sets an exception if it didn't find the thing. */
PyErr_Clear();
/* A new concurrency object. Make a new data stack. */
the_index = self->data_stacks_used;
stack_index = PyLong_FromLong((long)the_index);
if (stack_index == NULL) {
goto error;
}
if (PyObject_SetItem(self->data_stack_index, co_obj, stack_index) < 0) {
goto error;
}
self->data_stacks_used++;
if (self->data_stacks_used >= self->data_stacks_alloc) {
int bigger = self->data_stacks_alloc + 10;
DataStack * bigger_stacks = PyMem_Realloc(self->data_stacks, bigger * sizeof(DataStack));
if (bigger_stacks == NULL) {
PyErr_NoMemory();
goto error;
}
self->data_stacks = bigger_stacks;
self->data_stacks_alloc = bigger;
}
DataStack_init(&self->stats, &self->data_stacks[the_index]);
}
else {
if (pyint_as_int(stack_index, &the_index) < 0) {
goto error;
}
}
self->pdata_stack = &self->data_stacks[the_index];
}
else {
self->pdata_stack = &self->data_stack;
}
ret = RET_OK;
error:
Py_XDECREF(co_obj);
Py_XDECREF(stack_index);
return ret;
}
// Thanks for the idea, memray!
static inline PyCodeObject*
MyFrame_BorrowCode(PyFrameObject* frame)
{
// Return a borrowed reference.
PyCodeObject* pCode = PyFrame_GetCode(frame);
assert(Py_REFCNT(pCode) >= 2);
Py_DECREF(pCode);
return pCode;
}
/*
* Parts of the trace function.
*/
static int
CTracer_handle_call(CTracer *self, PyFrameObject *frame)
{
int ret = RET_ERROR;
int ret2;
/* Owned references that we clean up at the very end of the function. */
PyObject * disposition = NULL;
PyObject * plugin = NULL;
PyObject * plugin_name = NULL;
PyObject * next_tracename = NULL;
#ifdef RESUME // >=3.11
PyObject * pCode = NULL;
#endif
/* Borrowed references. */
PyObject * filename = NULL;
PyObject * disp_trace = NULL;
PyObject * tracename = NULL;
PyObject * file_tracer = NULL;
PyObject * has_dynamic_filename = NULL;
CFileDisposition * pdisp = NULL;
STATS( self->stats.calls++; )
/* Grow the stack. */
if (CTracer_set_pdata_stack(self) < 0) {
goto error;
}
if (DataStack_grow(&self->stats, self->pdata_stack) < 0) {
goto error;
}
self->pcur_entry = &self->pdata_stack->stack[self->pdata_stack->depth];
/* See if this frame begins a new context. */
if (self->should_start_context != Py_None && self->context == Py_None) {
PyObject * context;
/* We're looking for our context, ask should_start_context if this is the start. */
STATS( self->stats.start_context_calls++; )
STATS( self->stats.pycalls++; )
context = PyObject_CallFunctionObjArgs(self->should_start_context, frame, NULL);
if (context == NULL) {
goto error;
}
if (context != Py_None) {
PyObject * val;
Py_DECREF(self->context);
self->context = context;
self->pcur_entry->started_context = TRUE;
STATS( self->stats.pycalls++; )
val = PyObject_CallFunctionObjArgs(self->switch_context, context, NULL);
if (val == NULL) {
goto error;
}
Py_DECREF(val);
}
else {
Py_DECREF(context);
self->pcur_entry->started_context = FALSE;
}
}
else {
self->pcur_entry->started_context = FALSE;
}
/* Check if we should trace this line. */
filename = MyFrame_BorrowCode(frame)->co_filename;
disposition = PyDict_GetItem(self->should_trace_cache, filename);
if (disposition == NULL) {
if (PyErr_Occurred()) {
goto error;
}
STATS( self->stats.files++; )
/* We've never considered this file before. */
/* Ask should_trace about it. */
STATS( self->stats.pycalls++; )
disposition = PyObject_CallFunctionObjArgs(self->should_trace, filename, frame, NULL);
if (disposition == NULL) {
/* An error occurred inside should_trace. */
goto error;
}
if (PyDict_SetItem(self->should_trace_cache, filename, disposition) < 0) {
goto error;
}
}
else {
Py_INCREF(disposition);
}
if (disposition == Py_None) {
/* A later check_include returned false, so don't trace it. */
disp_trace = Py_False;
}
else {
/* The object we got is a CFileDisposition, use it efficiently. */
pdisp = (CFileDisposition *) disposition;
disp_trace = pdisp->trace;
if (disp_trace == NULL) {
goto error;
}
}
if (disp_trace == Py_True) {
/* If tracename is a string, then we're supposed to trace. */
tracename = pdisp->source_filename;
if (tracename == NULL) {
goto error;
}
file_tracer = pdisp->file_tracer;
if (file_tracer == NULL) {
goto error;
}
if (file_tracer != Py_None) {
plugin = PyObject_GetAttr(file_tracer, str__coverage_plugin);
if (plugin == NULL) {
goto error;
}
plugin_name = PyObject_GetAttr(plugin, str__coverage_plugin_name);
if (plugin_name == NULL) {
goto error;
}
}
has_dynamic_filename = pdisp->has_dynamic_filename;
if (has_dynamic_filename == NULL) {
goto error;
}
if (has_dynamic_filename == Py_True) {
STATS( self->stats.pycalls++; )
next_tracename = PyObject_CallMethodObjArgs(
file_tracer, str_dynamic_source_filename,
tracename, frame, NULL
);
if (next_tracename == NULL) {
/* An exception from the function. Alert the user with a
* warning and a traceback.
*/
CTracer_disable_plugin(self, disposition);
/* Because we handled the error, goto ok. */
goto ok;
}
tracename = next_tracename;
if (tracename != Py_None) {
/* Check the dynamic source filename against the include rules. */
PyObject * included = NULL;
int should_include;
included = PyDict_GetItem(self->should_trace_cache, tracename);
if (included == NULL) {
PyObject * should_include_bool;
if (PyErr_Occurred()) {
goto error;
}
STATS( self->stats.files++; )
STATS( self->stats.pycalls++; )
should_include_bool = PyObject_CallFunctionObjArgs(self->check_include, tracename, frame, NULL);
if (should_include_bool == NULL) {
goto error;
}
should_include = (should_include_bool == Py_True);
Py_DECREF(should_include_bool);
if (PyDict_SetItem(self->should_trace_cache, tracename, should_include ? disposition : Py_None) < 0) {
goto error;
}
}
else {
should_include = (included != Py_None);
}
if (!should_include) {
tracename = Py_None;
}
}
}
}
else {
tracename = Py_None;
}
if (tracename != Py_None) {
PyObject * file_data;
BOOL had_error = FALSE;
PyObject * res;
res = PyObject_CallFunctionObjArgs(self->lock_data, NULL);
if (res == NULL) {
goto error;
}
file_data = PyDict_GetItem(self->data, tracename);
if (file_data == NULL) {
if (PyErr_Occurred()) {
had_error = TRUE;
goto unlock;
}
file_data = PySet_New(NULL);
if (file_data == NULL) {
had_error = TRUE;
goto unlock;
}
ret2 = PyDict_SetItem(self->data, tracename, file_data);
if (ret2 < 0) {
had_error = TRUE;
goto unlock;
}
/* If the disposition mentions a plugin, record that. */
if (file_tracer != Py_None) {
ret2 = PyDict_SetItem(self->file_tracers, tracename, plugin_name);
if (ret2 < 0) {
had_error = TRUE;
goto unlock;
}
}
}
else {
/* PyDict_GetItem gives a borrowed reference. Own it. */
Py_INCREF(file_data);
}
unlock:
res = PyObject_CallFunctionObjArgs(self->unlock_data, NULL);
if (res == NULL) {
goto error;
}
if (had_error) {
goto error;
}
Py_XDECREF(self->pcur_entry->file_data);
self->pcur_entry->file_data = file_data;
self->pcur_entry->file_tracer = file_tracer;
SHOWLOG(PyFrame_GetLineNumber(frame), filename, "traced");
}
else {
Py_XDECREF(self->pcur_entry->file_data);
self->pcur_entry->file_data = NULL;
self->pcur_entry->file_tracer = Py_None;
MyFrame_NoTraceLines(frame);
SHOWLOG(PyFrame_GetLineNumber(frame), filename, "skipped");
}
self->pcur_entry->disposition = disposition;
/* Make the frame right in case settrace(gettrace()) happens. */
MyFrame_SetTrace(frame, self);
/* A call event is really a "start frame" event, and can happen for
* re-entering a generator also. How we tell the difference depends on
* the version of Python.
*/
BOOL real_call = FALSE;
#ifdef RESUME
/*
* The current opcode is guaranteed to be RESUME. The argument
* determines what kind of resume it is.
*/
pCode = MyCode_GetCode(MyFrame_BorrowCode(frame));
real_call = (PyBytes_AS_STRING(pCode)[MyFrame_GetLasti(frame) + 1] == 0);
#else
// f_lasti is -1 for a true call, and a real byte offset for a generator re-entry.
real_call = (MyFrame_GetLasti(frame) < 0);
#endif
if (real_call) {
self->pcur_entry->last_line = -MyFrame_BorrowCode(frame)->co_firstlineno;
}
else {
self->pcur_entry->last_line = PyFrame_GetLineNumber(frame);
}
ok:
ret = RET_OK;
error:
#ifdef RESUME
MyCode_FreeCode(pCode);
#endif
Py_XDECREF(next_tracename);
Py_XDECREF(disposition);
Py_XDECREF(plugin);
Py_XDECREF(plugin_name);
return ret;
}
static void
CTracer_disable_plugin(CTracer *self, PyObject * disposition)
{
PyObject * ret;
PyErr_Print();
STATS( self->stats.pycalls++; )
ret = PyObject_CallFunctionObjArgs(self->disable_plugin, disposition, NULL);
if (ret == NULL) {
goto error;
}
Py_DECREF(ret);
return;
error:
/* This function doesn't return a status, so if an error happens, print it,
* but don't interrupt the flow. */
/* PySys_WriteStderr is nicer, but is not in the public API. */
fprintf(stderr, "Error occurred while disabling plug-in:\n");
PyErr_Print();
}
static int
CTracer_unpack_pair(CTracer *self, PyObject *pair, int *p_one, int *p_two)
{
int ret = RET_ERROR;
int the_int;
PyObject * pyint = NULL;
int index;
if (!PyTuple_Check(pair) || PyTuple_Size(pair) != 2) {
PyErr_SetString(
PyExc_TypeError,
"line_number_range must return 2-tuple"
);
goto error;
}
for (index = 0; index < 2; index++) {
pyint = PyTuple_GetItem(pair, index);
if (pyint == NULL) {
goto error;
}
if (pyint_as_int(pyint, &the_int) < 0) {
goto error;
}
*(index == 0 ? p_one : p_two) = the_int;
}
ret = RET_OK;
error:
return ret;
}
static int
CTracer_handle_line(CTracer *self, PyFrameObject *frame)
{
int ret = RET_ERROR;
int ret2;
STATS( self->stats.lines++; )
if (self->pdata_stack->depth >= 0) {
SHOWLOG(PyFrame_GetLineNumber(frame), MyFrame_BorrowCode(frame)->co_filename, "line");
if (self->pcur_entry->file_data) {
int lineno_from = -1;
int lineno_to = -1;
/* We're tracing in this frame: record something. */
if (self->pcur_entry->file_tracer != Py_None) {
PyObject * from_to = NULL;
STATS( self->stats.pycalls++; )
from_to = PyObject_CallMethodObjArgs(self->pcur_entry->file_tracer, str_line_number_range, frame, NULL);
if (from_to == NULL) {
CTracer_disable_plugin(self, self->pcur_entry->disposition);
goto ok;
}
ret2 = CTracer_unpack_pair(self, from_to, &lineno_from, &lineno_to);
Py_DECREF(from_to);
if (ret2 < 0) {
CTracer_disable_plugin(self, self->pcur_entry->disposition);
goto ok;
}
}
else {
lineno_from = lineno_to = PyFrame_GetLineNumber(frame);
}
if (lineno_from != -1) {
for (; lineno_from <= lineno_to; lineno_from++) {
if (self->tracing_arcs) {
/* Tracing arcs: key is (last_line,this_line). */
if (CTracer_record_pair(self, self->pcur_entry->last_line, lineno_from) < 0) {
goto error;
}
}
else {
/* Tracing lines: key is simply this_line. */
PyObject * this_line = PyLong_FromLong((long)lineno_from);
if (this_line == NULL) {
goto error;
}
ret2 = PySet_Add(self->pcur_entry->file_data, this_line);
Py_DECREF(this_line);
if (ret2 < 0) {
goto error;
}
}
self->pcur_entry->last_line = lineno_from;
}
}
}
}
ok:
ret = RET_OK;
error:
return ret;
}
static int
CTracer_handle_return(CTracer *self, PyFrameObject *frame)
{
int ret = RET_ERROR;
PyObject * pCode = NULL;
STATS( self->stats.returns++; )
/* A near-copy of this code is above in the missing-return handler. */
if (CTracer_set_pdata_stack(self) < 0) {
goto error;
}
if (self->pdata_stack->depth >= 0) {
self->pcur_entry = &self->pdata_stack->stack[self->pdata_stack->depth];
if (self->tracing_arcs && self->pcur_entry->file_data) {
BOOL real_return = FALSE;
pCode = MyCode_GetCode(MyFrame_BorrowCode(frame));
int lasti = MyFrame_GetLasti(frame);
Py_ssize_t code_size = PyBytes_GET_SIZE(pCode);
unsigned char * code_bytes = (unsigned char *)PyBytes_AS_STRING(pCode);
#ifdef RESUME
if (lasti == code_size - 2) {
real_return = TRUE;
}
else {
#if ENV_LASTI_IS_YIELD
lasti += 2;
#endif
real_return = (code_bytes[lasti] != RESUME);
}
#else
/* Need to distinguish between RETURN_VALUE and YIELD_VALUE. Read
* the current bytecode to see what it is. In unusual circumstances
* (Cython code), co_code can be the empty string, so range-check
* f_lasti before reading the byte.
*/
BOOL is_yield = FALSE;
BOOL is_yield_from = FALSE;
if (lasti < code_size) {
is_yield = (code_bytes[lasti] == YIELD_VALUE);
if (lasti + 2 < code_size) {
is_yield_from = (code_bytes[lasti + 2] == YIELD_FROM);
}
}
real_return = !(is_yield || is_yield_from);
#endif
if (real_return) {
int first = MyFrame_BorrowCode(frame)->co_firstlineno;
if (CTracer_record_pair(self, self->pcur_entry->last_line, -first) < 0) {
goto error;
}
}
}
/* If this frame started a context, then returning from it ends the context. */
if (self->pcur_entry->started_context) {
PyObject * val;
Py_DECREF(self->context);
self->context = Py_None;
Py_INCREF(self->context);
STATS( self->stats.pycalls++; )
val = PyObject_CallFunctionObjArgs(self->switch_context, self->context, NULL);
if (val == NULL) {
goto error;
}
Py_DECREF(val);
}
/* Pop the stack. */
SHOWLOG(PyFrame_GetLineNumber(frame), MyFrame_BorrowCode(frame)->co_filename, "return");
self->pdata_stack->depth--;
self->pcur_entry = &self->pdata_stack->stack[self->pdata_stack->depth];
}
ret = RET_OK;
error:
MyCode_FreeCode(pCode);
return ret;
}
/*
* The Trace Function
*/
static int
CTracer_trace(CTracer *self, PyFrameObject *frame, int what, PyObject *arg_unused)
{
int ret = RET_ERROR;
#if DO_NOTHING
return RET_OK;
#endif
if (!atomic_load(&self->started)) {
/* If CTracer.stop() has been called from another thread, the tracer
is still active in the current thread. Let's deactivate ourselves
now. */
PyEval_SetTrace(NULL, NULL);
return RET_OK;
}
#if WHAT_LOG || TRACE_LOG
PyObject * ascii = NULL;
#endif
#if WHAT_LOG
const char * w = "XXX ";
if (what <= (int)(sizeof(what_sym)/sizeof(const char *))) {
w = what_sym[what];
}
ascii = PyUnicode_AsASCIIString(MyFrame_BorrowCode(frame)->co_filename);
printf("%x trace: f:%x %s @ %s %d\n", (int)self, (int)frame, what_sym[what], PyBytes_AS_STRING(ascii), PyFrame_GetLineNumber(frame));
Py_DECREF(ascii);
#endif
#if TRACE_LOG
ascii = PyUnicode_AsASCIIString(MyFrame_BorrowCode(frame)->co_filename);
if (strstr(PyBytes_AS_STRING(ascii), start_file) && PyFrame_GetLineNumber(frame) == start_line) {
logging = TRUE;
}
Py_DECREF(ascii);
#endif
atomic_store(&self->activity, TRUE);
switch (what) {
case PyTrace_CALL:
if (CTracer_handle_call(self, frame) < 0) {
goto error;
}
break;
case PyTrace_RETURN:
if (CTracer_handle_return(self, frame) < 0) {
goto error;
}
break;
case PyTrace_LINE:
if (CTracer_handle_line(self, frame) < 0) {
goto error;
}
break;
default:
STATS( self->stats.others++; )
break;
}
ret = RET_OK;
goto cleanup;
error:
STATS( self->stats.errors++; )
cleanup:
return ret;
}
/*
* Python has two ways to set the trace function: sys.settrace(fn), which
* takes a Python callable, and PyEval_SetTrace(func, obj), which takes
* a C function and a Python object. The way these work together is that
* sys.settrace(pyfn) calls PyEval_SetTrace(builtin_func, pyfn), using the
* Python callable as the object in PyEval_SetTrace. So sys.gettrace()
* simply returns the Python object used as the second argument to
* PyEval_SetTrace. So sys.gettrace() will return our self parameter, which
* means it must be callable to be used in sys.settrace().
*
* So we make ourself callable, equivalent to invoking our trace function.
*/
static PyObject *
CTracer_call(CTracer *self, PyObject *args, PyObject *kwds)
{
PyFrameObject *frame;
PyObject *what_str;
PyObject *arg;
int what;
PyObject *ret = NULL;
PyObject * ascii = NULL;
#if DO_NOTHING
CRASH
#endif
static char *what_names[] = {
"call", "exception", "line", "return",
"c_call", "c_exception", "c_return",
NULL
};
static char *kwlist[] = {"frame", "event", "arg", NULL};
if (!PyArg_ParseTupleAndKeywords(args, kwds, "O!O!O|i:Tracer_call", kwlist,
&PyFrame_Type, &frame, &PyUnicode_Type, &what_str, &arg)) {
goto done;
}
/* In Python, the what argument is a string, we need to find an int
for the C function. */
for (what = 0; what_names[what]; what++) {
int should_break;
ascii = PyUnicode_AsASCIIString(what_str);
should_break = !strcmp(PyBytes_AS_STRING(ascii), what_names[what]);
Py_DECREF(ascii);
if (should_break) {
break;
}
}
#if WHAT_LOG
ascii = PyUnicode_AsASCIIString(MyFrame_BorrowCode(frame)->co_filename);
printf("pytrace: %s @ %s %d\n", what_sym[what], PyBytes_AS_STRING(ascii), PyFrame_GetLineNumber(frame));
Py_DECREF(ascii);
#endif
/* Invoke the C function, and return ourselves. */
if (CTracer_trace(self, frame, what, arg) == RET_OK) {
Py_INCREF(self);
ret = (PyObject *)self;
}
/* For better speed, install ourselves the C way so that future calls go
directly to CTracer_trace, without this intermediate function.
Only do this if this is a CALL event, since new trace functions only
take effect then. If we don't condition it on CALL, then we'll clobber
the new trace function before it has a chance to get called. To
understand why, there are three internal values to track: frame.f_trace,
c_tracefunc, and c_traceobj. They are explained here:
https://nedbatchelder.com/text/trace-function.html
Without the conditional on PyTrace_CALL, this is what happens:
def func(): # f_trace c_tracefunc c_traceobj
# -------------- -------------- --------------
# CTracer CTracer.trace CTracer
sys.settrace(my_func)
# CTracer trampoline my_func
# Now Python calls trampoline(CTracer), which calls this function
# which calls PyEval_SetTrace below, setting us as the tracer again:
# CTracer CTracer.trace CTracer
# and it's as if the settrace never happened.
*/
if (what == PyTrace_CALL) {
PyEval_SetTrace((Py_tracefunc)CTracer_trace, (PyObject*)self);
}
done:
return ret;
}
static PyObject *
CTracer_start(CTracer *self, PyObject *args_unused)
{
assert(atomic_load(&self->started) == FALSE);
PyEval_SetTrace((Py_tracefunc)CTracer_trace, (PyObject*)self);
self->tracing_arcs = self->trace_arcs && PyObject_IsTrue(self->trace_arcs);
atomic_store(&self->started, TRUE);
/* start() returns a trace function usable with sys.settrace() */
Py_INCREF(self);
return (PyObject *)self;
}
static PyObject *
CTracer_stop(CTracer *self, PyObject *args_unused)
{
/* Set the started flag only. The actual call to
PyEval_SetTrace(NULL, NULL) is delegated to the callback
itself to ensure that it called from the right thread.
*/
atomic_store(&self->started, FALSE);
Py_RETURN_NONE;
}
static PyObject *
CTracer_activity(CTracer *self, PyObject *args_unused)
{
if (atomic_load(&self->activity)) {
Py_RETURN_TRUE;
}
else {
Py_RETURN_FALSE;
}
}
static PyObject *
CTracer_reset_activity(CTracer *self, PyObject *args_unused)
{
atomic_store(&self->activity, FALSE);
Py_RETURN_NONE;
}
static PyObject *
CTracer_get_stats(CTracer *self, PyObject *args_unused)
{
#if COLLECT_STATS
return Py_BuildValue(
"{sI,sI,sI,sI,sI,sI,si,sI,sI,sI}",
"calls", self->stats.calls,
"lines", self->stats.lines,
"returns", self->stats.returns,
"others", self->stats.others,
"files", self->stats.files,
"stack_reallocs", self->stats.stack_reallocs,
"stack_alloc", self->pdata_stack->alloc,
"errors", self->stats.errors,
"pycalls", self->stats.pycalls,
"start_context_calls", self->stats.start_context_calls
);
#else
Py_RETURN_NONE;
#endif /* COLLECT_STATS */
}
static PyMemberDef
CTracer_members[] = {
{ "should_trace", T_OBJECT, offsetof(CTracer, should_trace), 0,
PyDoc_STR("Function indicating whether to trace a file.") },
{ "check_include", T_OBJECT, offsetof(CTracer, check_include), 0,
PyDoc_STR("Function indicating whether to include a file.") },
{ "warn", T_OBJECT, offsetof(CTracer, warn), 0,
PyDoc_STR("Function for issuing warnings.") },
{ "concur_id_func", T_OBJECT, offsetof(CTracer, concur_id_func), 0,
PyDoc_STR("Function for determining concurrency context") },
{ "data", T_OBJECT, offsetof(CTracer, data), 0,
PyDoc_STR("The raw dictionary of trace data.") },
{ "file_tracers", T_OBJECT, offsetof(CTracer, file_tracers), 0,
PyDoc_STR("Mapping from file name to plugin name.") },
{ "should_trace_cache", T_OBJECT, offsetof(CTracer, should_trace_cache), 0,
PyDoc_STR("Dictionary caching should_trace results.") },
{ "trace_arcs", T_OBJECT, offsetof(CTracer, trace_arcs), 0,
PyDoc_STR("Should we trace arcs, or just lines?") },
{ "should_start_context", T_OBJECT, offsetof(CTracer, should_start_context), 0,
PyDoc_STR("Function for starting contexts.") },
{ "switch_context", T_OBJECT, offsetof(CTracer, switch_context), 0,
PyDoc_STR("Function for switching to a new context.") },
{ "lock_data", T_OBJECT, offsetof(CTracer, lock_data), 0,
PyDoc_STR("Function for locking access to self.data.") },
{ "unlock_data", T_OBJECT, offsetof(CTracer, unlock_data), 0,
PyDoc_STR("Function for unlocking access to self.data.") },
{ "disable_plugin", T_OBJECT, offsetof(CTracer, disable_plugin), 0,
PyDoc_STR("Function for disabling a plugin.") },
{ NULL }
};
static PyMethodDef
CTracer_methods[] = {
{ "start", (PyCFunction) CTracer_start, METH_VARARGS,
PyDoc_STR("Start the tracer") },
{ "stop", (PyCFunction) CTracer_stop, METH_VARARGS,
PyDoc_STR("Stop the tracer") },
{ "get_stats", (PyCFunction) CTracer_get_stats, METH_VARARGS,
PyDoc_STR("Get statistics about the tracing") },
{ "activity", (PyCFunction) CTracer_activity, METH_VARARGS,
PyDoc_STR("Has there been any activity?") },
{ "reset_activity", (PyCFunction) CTracer_reset_activity, METH_VARARGS,
PyDoc_STR("Reset the activity flag") },
{ NULL }
};
PyTypeObject
CTracerType = {
PyVarObject_HEAD_INIT(NULL, 0)
"coverage.CTracer", /*tp_name*/
sizeof(CTracer), /*tp_basicsize*/
0, /*tp_itemsize*/
(destructor)CTracer_dealloc, /*tp_dealloc*/
0, /*tp_print*/
0, /*tp_getattr*/
0, /*tp_setattr*/
0, /*tp_compare*/
0, /*tp_repr*/
0, /*tp_as_number*/
0, /*tp_as_sequence*/
0, /*tp_as_mapping*/
0, /*tp_hash */
(ternaryfunc)CTracer_call, /*tp_call*/
0, /*tp_str*/
0, /*tp_getattro*/
0, /*tp_setattro*/
0, /*tp_as_buffer*/
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
"CTracer objects", /* tp_doc */
0, /* tp_traverse */
0, /* tp_clear */
0, /* tp_richcompare */
0, /* tp_weaklistoffset */
0, /* tp_iter */
0, /* tp_iternext */
CTracer_methods, /* tp_methods */
CTracer_members, /* tp_members */
0, /* tp_getset */
0, /* tp_base */
0, /* tp_dict */
0, /* tp_descr_get */
0, /* tp_descr_set */
0, /* tp_dictoffset */
(initproc)CTracer_init, /* tp_init */
0, /* tp_alloc */
0, /* tp_new */
};
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/ctracer/tracer.h 0000644 0001751 0001751 00000004010 15073731535 017714 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
#ifndef _COVERAGE_TRACER_H
#define _COVERAGE_TRACER_H
#include "util.h"
#include "structmember.h"
#include "frameobject.h"
#include "opcode.h"
#include "datastack.h"
/* The CTracer type. */
typedef struct CTracer {
PyObject_HEAD
/* Python objects manipulated directly by the Collector class. */
PyObject * should_trace;
PyObject * check_include;
PyObject * warn;
PyObject * concur_id_func;
PyObject * data;
PyObject * file_tracers;
PyObject * should_trace_cache;
PyObject * trace_arcs;
PyObject * should_start_context;
PyObject * switch_context;
PyObject * lock_data;
PyObject * unlock_data;
PyObject * disable_plugin;
/* Has the tracer been started? */
_Atomic BOOL started;
/* Are we tracing arcs, or just lines? */
BOOL tracing_arcs;
/* Have we had any activity? */
_Atomic BOOL activity;
/* The current dynamic context. */
PyObject * context;
/*
The data stack is a stack of sets. Each set collects
data for a single source file. The data stack parallels the call stack:
each call pushes the new frame's file data onto the data stack, and each
return pops file data off.
The file data is a set whose form depends on the tracing options.
If tracing arcs, the values are line number pairs. If not tracing arcs,
the values are line numbers.
*/
DataStack data_stack; /* Used if we aren't doing concurrency. */
PyObject * data_stack_index; /* Used if we are doing concurrency. */
DataStack * data_stacks;
int data_stacks_alloc;
int data_stacks_used;
DataStack * pdata_stack;
/* The current file's data stack entry. */
DataStackEntry * pcur_entry;
Stats stats;
} CTracer;
int CTracer_intern_strings(void);
extern PyTypeObject CTracerType;
#endif /* _COVERAGE_TRACER_H */
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/ctracer/util.h 0000644 0001751 0001751 00000005333 15073731535 017422 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
#ifndef _COVERAGE_UTIL_H
#define _COVERAGE_UTIL_H
#include
#include
/* Compile-time debugging helpers */
#undef WHAT_LOG /* Define to log the WHAT params in the trace function. */
#undef TRACE_LOG /* Define to log our bookkeeping. */
#undef COLLECT_STATS /* Collect counters: stats are printed when tracer is stopped. */
#undef DO_NOTHING /* Define this to make the tracer do nothing. */
#if PY_VERSION_HEX >= 0x030B00A0
// 3.11 moved f_lasti into an internal structure. This is totally the wrong way
// to make this work, but it's all I've got until https://bugs.python.org/issue40421
// is resolved.
#if PY_VERSION_HEX < 0x030D0000
#include
#endif
#if PY_VERSION_HEX >= 0x030B00A7
#define MyFrame_GetLasti(f) (PyFrame_GetLasti(f))
#else
#define MyFrame_GetLasti(f) ((f)->f_frame->f_lasti * 2)
#endif
#else
// The f_lasti field changed meaning in 3.10.0a7. It had been bytes, but
// now is instructions, so we need to adjust it to use it as a byte index.
#define MyFrame_GetLasti(f) ((f)->f_lasti * 2)
#endif
#if PY_VERSION_HEX >= 0x030D0000
#define MyFrame_NoTraceLines(f) (PyObject_SetAttrString((PyObject*)(f), "f_trace_lines", Py_False))
#define MyFrame_SetTrace(f, obj) (PyObject_SetAttrString((PyObject*)(f), "f_trace", (PyObject*)(obj)))
#else
#define MyFrame_NoTraceLines(f) ((f)->f_trace_lines = 0)
#define MyFrame_SetTrace(f, obj) {Py_INCREF(obj); Py_XSETREF((f)->f_trace, (PyObject*)(obj));}
#endif
#if PY_VERSION_HEX >= 0x030B00B1
#define MyCode_GetCode(co) (PyCode_GetCode(co))
#define MyCode_FreeCode(code) Py_XDECREF(code)
#elif PY_VERSION_HEX >= 0x030B00A7
#define MyCode_GetCode(co) (PyObject_GetAttrString((PyObject *)(co), "co_code"))
#define MyCode_FreeCode(code) Py_XDECREF(code)
#else
#define MyCode_GetCode(co) ((co)->co_code)
#define MyCode_FreeCode(code)
#endif
// Where does frame.f_lasti point when yielding from a generator?
// It used to point at the YIELD, in 3.13 it points at the RESUME,
// then it went back to the YIELD.
// https://github.com/python/cpython/issues/113728
#define ENV_LASTI_IS_YIELD ((PY_VERSION_HEX & 0xFFFF0000) != 0x030D0000)
/* The values returned to indicate ok or error. */
#define RET_OK 0
#define RET_ERROR -1
/* Nicer booleans */
typedef int BOOL;
#define FALSE 0
#define TRUE 1
#if SIZEOF_LONG_LONG < 8
#error long long too small!
#endif
typedef unsigned long long uint64;
/* Only for extreme machete-mode debugging! */
#define CRASH { printf("*** CRASH! ***\n"); *((int*)1) = 1; }
#endif /* _COVERAGE_UTIL_H */
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/data.py 0000644 0001751 0001751 00000017675 15073731535 016150 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Coverage data for coverage.py.
This file had the 4.x JSON data support, which is now gone. This file still
has storage-agnostic helpers, and is kept to avoid changing too many imports.
CoverageData is now defined in sqldata.py, and imported here to keep the
imports working.
"""
from __future__ import annotations
import functools
import glob
import hashlib
import os.path
from collections.abc import Iterable
from typing import Callable
from coverage.exceptions import CoverageException, NoDataError
from coverage.files import PathAliases
from coverage.misc import Hasher, file_be_gone, human_sorted, plural
from coverage.sqldata import CoverageData as CoverageData # pylint: disable=useless-import-alias
def line_counts(data: CoverageData, fullpath: bool = False) -> dict[str, int]:
"""Return a dict summarizing the line coverage data.
Keys are based on the file names, and values are the number of executed
lines. If `fullpath` is true, then the keys are the full pathnames of
the files, otherwise they are the basenames of the files.
Returns a dict mapping file names to counts of lines.
"""
summ = {}
filename_fn: Callable[[str], str]
if fullpath:
# pylint: disable=unnecessary-lambda-assignment
filename_fn = lambda f: f
else:
filename_fn = os.path.basename
for filename in data.measured_files():
lines = data.lines(filename)
assert lines is not None
summ[filename_fn(filename)] = len(lines)
return summ
def add_data_to_hash(data: CoverageData, filename: str, hasher: Hasher) -> None:
"""Contribute `filename`'s data to the `hasher`.
`hasher` is a `coverage.misc.Hasher` instance to be updated with
the file's data. It should only get the results data, not the run
data.
"""
if data.has_arcs():
hasher.update(sorted(data.arcs(filename) or []))
else:
hasher.update(sorted_lines(data, filename))
hasher.update(data.file_tracer(filename))
def combinable_files(data_file: str, data_paths: Iterable[str] | None = None) -> list[str]:
"""Make a list of data files to be combined.
`data_file` is a path to a data file. `data_paths` is a list of files or
directories of files.
Returns a list of absolute file paths.
"""
data_dir, local = os.path.split(os.path.abspath(data_file))
data_paths = data_paths or [data_dir]
files_to_combine = []
for p in data_paths:
if os.path.isfile(p):
files_to_combine.append(os.path.abspath(p))
elif os.path.isdir(p):
pattern = glob.escape(os.path.join(os.path.abspath(p), local)) + ".*"
files_to_combine.extend(glob.glob(pattern))
else:
raise NoDataError(f"Couldn't combine from non-existent path '{p}'")
# SQLite might have made journal files alongside our database files.
# We never want to combine those.
files_to_combine = [fnm for fnm in files_to_combine if not fnm.endswith("-journal")]
# Sorting isn't usually needed, since it shouldn't matter what order files
# are combined, but sorting makes tests more predictable, and makes
# debugging more understandable when things go wrong.
return sorted(files_to_combine)
def combine_parallel_data(
data: CoverageData,
aliases: PathAliases | None = None,
data_paths: Iterable[str] | None = None,
strict: bool = False,
keep: bool = False,
message: Callable[[str], None] | None = None,
) -> None:
"""Combine a number of data files together.
`data` is a CoverageData.
Treat `data.filename` as a file prefix, and combine the data from all
of the data files starting with that prefix plus a dot.
If `aliases` is provided, it's a `PathAliases` object that is used to
re-map paths to match the local machine's.
If `data_paths` is provided, it is a list of directories or files to
combine. Directories are searched for files that start with
`data.filename` plus dot as a prefix, and those files are combined.
If `data_paths` is not provided, then the directory portion of
`data.filename` is used as the directory to search for data files.
Unless `keep` is True every data file found and combined is then deleted
from disk. If a file cannot be read, a warning will be issued, and the
file will not be deleted.
If `strict` is true, and no files are found to combine, an error is
raised.
`message` is a function to use for printing messages to the user.
"""
files_to_combine = combinable_files(data.base_filename(), data_paths)
if strict and not files_to_combine:
raise NoDataError("No data to combine")
if aliases is None:
map_path = None
else:
map_path = functools.cache(aliases.map)
file_hashes = set()
combined_any = False
for f in files_to_combine:
if f == data.data_filename():
# Sometimes we are combining into a file which is one of the
# parallel files. Skip that file.
if data._debug.should("dataio"):
data._debug.write(f"Skipping combining ourself: {f!r}")
continue
try:
rel_file_name = os.path.relpath(f)
except ValueError:
# ValueError can be raised under Windows when os.getcwd() returns a
# folder from a different drive than the drive of f, in which case
# we print the original value of f instead of its relative path
rel_file_name = f
with open(f, "rb") as fobj:
hasher = hashlib.new("sha3_256", usedforsecurity=False)
hasher.update(fobj.read())
sha = hasher.digest()
combine_this_one = sha not in file_hashes
delete_this_one = not keep
if combine_this_one:
if data._debug.should("dataio"):
data._debug.write(f"Combining data file {f!r}")
file_hashes.add(sha)
try:
new_data = CoverageData(f, debug=data._debug)
new_data.read()
except CoverageException as exc:
if data._warn:
# The CoverageException has the file name in it, so just
# use the message as the warning.
data._warn(str(exc))
if message:
message(f"Couldn't combine data file {rel_file_name}: {exc}")
delete_this_one = False
else:
data.update(new_data, map_path=map_path)
combined_any = True
if message:
message(f"Combined data file {rel_file_name}")
else:
if message:
message(f"Skipping duplicate data {rel_file_name}")
if delete_this_one:
if data._debug.should("dataio"):
data._debug.write(f"Deleting data file {f!r}")
file_be_gone(f)
if strict and not combined_any:
raise NoDataError("No usable data files")
def debug_data_file(filename: str) -> None:
"""Implementation of 'coverage debug data'."""
data = CoverageData(filename)
filename = data.data_filename()
print(f"path: {filename}")
if not os.path.exists(filename):
print("No data collected: file doesn't exist")
return
data.read()
print(f"has_arcs: {data.has_arcs()!r}")
summary = line_counts(data, fullpath=True)
filenames = human_sorted(summary.keys())
nfiles = len(filenames)
print(f"{nfiles} file{plural(nfiles)}:")
for f in filenames:
line = f"{f}: {summary[f]} line{plural(summary[f])}"
plugin = data.file_tracer(f)
if plugin:
line += f" [{plugin}]"
print(line)
def sorted_lines(data: CoverageData, filename: str) -> list[int]:
"""Get the sorted lines for a file, for tests."""
lines = data.lines(filename)
return sorted(lines or [])
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/debug.py 0000644 0001751 0001751 00000052102 15073731535 016305 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Control of and utilities for debugging."""
from __future__ import annotations
import _thread
import atexit
import contextlib
import datetime
import functools
import inspect
import itertools
import os
import pprint
import re
import reprlib
import sys
import traceback
import types
from collections.abc import Iterable, Iterator, Mapping
from typing import IO, Any, Callable, Final, overload
from coverage.misc import human_sorted_items, isolate_module
from coverage.types import AnyCallable, TWritable
os = isolate_module(os)
# When debugging, it can be helpful to force some options, especially when
# debugging the configuration mechanisms you usually use to control debugging!
# This is a list of forced debugging options.
FORCED_DEBUG: list[str] = []
FORCED_DEBUG_FILE = None
class DebugControl:
"""Control and output for debugging."""
show_repr_attr = False # For auto_repr
def __init__(
self,
options: Iterable[str],
output: IO[str] | None,
file_name: str | None = None,
) -> None:
"""Configure the options and output file for debugging."""
self.options = list(options) + FORCED_DEBUG
self.suppress_callers = False
filters = []
if self.should("process"):
filters.append(CwdTracker().filter)
filters.append(ProcessTracker().filter)
if self.should("pytest"):
filters.append(PytestTracker().filter)
if self.should("pid"):
filters.append(add_pid_and_tid)
self.output = DebugOutputFile.get_one(
output,
file_name=file_name,
filters=filters,
)
self.raw_output = self.output.outfile
def __repr__(self) -> str:
return f""
def should(self, option: str) -> bool:
"""Decide whether to output debug information in category `option`."""
if option == "callers" and self.suppress_callers:
return False
return option in self.options
@contextlib.contextmanager
def without_callers(self) -> Iterator[None]:
"""A context manager to prevent call stacks from being logged."""
old = self.suppress_callers
self.suppress_callers = True
try:
yield
finally:
self.suppress_callers = old
def write(self, msg: str, *, exc: BaseException | None = None) -> None:
"""Write a line of debug output.
`msg` is the line to write. A newline will be appended.
If `exc` is provided, a stack trace of the exception will be written
after the message.
"""
self.output.write(msg + "\n")
if exc is not None:
self.output.write("".join(traceback.format_exception(None, exc, exc.__traceback__)))
if self.should("self"):
caller_self = inspect.stack()[1][0].f_locals.get("self")
if caller_self is not None:
self.output.write(f"self: {caller_self!r}\n")
if self.should("callers"):
dump_stack_frames(out=self.output, skip=1)
self.output.flush()
class NoDebugging(DebugControl):
"""A replacement for DebugControl that will never try to do anything."""
def __init__(self) -> None:
# pylint: disable=super-init-not-called
pass
def should(self, option: str) -> bool:
"""Should we write debug messages? Never."""
return False
@contextlib.contextmanager
def without_callers(self) -> Iterator[None]:
"""A dummy context manager to satisfy the api."""
yield # pragma: never called
def write(self, msg: str, *, exc: BaseException | None = None) -> None:
"""This will never be called."""
raise AssertionError("NoDebugging.write should never be called.")
class DevNullDebug(NoDebugging):
"""A DebugControl that won't write anywhere."""
def write(self, msg: str, *, exc: BaseException | None = None) -> None:
pass
def info_header(label: str) -> str:
"""Make a nice header string."""
return "--{:-<60s}".format(" " + label + " ")
def info_formatter(info: Iterable[tuple[str, Any]]) -> Iterator[str]:
"""Produce a sequence of formatted lines from info.
`info` is a sequence of pairs (label, data). The produced lines are
nicely formatted, ready to print.
"""
info = list(info)
if not info:
return
LABEL_LEN = 30
assert all(len(l) < LABEL_LEN for l, _ in info)
for label, data in info:
if data == []:
data = "-none-"
prefix = f"{label:>{LABEL_LEN}}: "
match data:
case tuple() if len(str(data)) < 30:
yield f"{prefix}{data}"
case tuple() | list() | set():
for e in data:
yield f"{prefix}{e}"
prefix = " " * (LABEL_LEN + 2)
case _:
yield f"{prefix}{data}"
def write_formatted_info(
write: Callable[[str], None],
header: str,
info: Iterable[tuple[str, Any]],
) -> None:
"""Write a sequence of (label,data) pairs nicely.
`write` is a function write(str) that accepts each line of output.
`header` is a string to start the section. `info` is a sequence of
(label, data) pairs, where label is a str, and data can be a single
value, or a list/set/tuple.
"""
write(info_header(header))
for line in info_formatter(info):
write(f" {line}")
def exc_one_line(exc: Exception) -> str:
"""Get a one-line summary of an exception, including class name and message."""
lines = traceback.format_exception_only(type(exc), exc)
return "|".join(l.rstrip() for l in lines)
_FILENAME_REGEXES: list[tuple[str, str]] = [
(r".*[/\\]pytest-of-.*[/\\]pytest-\d+([/\\]popen-gw\d+)?", "tmp:"),
]
_FILENAME_SUBS: list[tuple[str, str]] = []
@overload
def short_filename(filename: str) -> str:
pass
@overload
def short_filename(filename: None) -> None:
pass
def short_filename(filename: str | None) -> str | None:
"""Shorten a file name. Directories are replaced by prefixes like 'syspath:'"""
if not _FILENAME_SUBS:
for pathdir in sys.path:
_FILENAME_SUBS.append((pathdir, "syspath:"))
import coverage
_FILENAME_SUBS.append((os.path.dirname(coverage.__file__), "cov:"))
_FILENAME_SUBS.sort(key=(lambda pair: len(pair[0])), reverse=True)
if filename is not None:
for pat, sub in _FILENAME_REGEXES:
filename = re.sub(pat, sub, filename)
for before, after in _FILENAME_SUBS:
filename = filename.replace(before, after)
return filename
def file_summary(filename: str) -> str:
"""A one-line summary of a file, for log messages."""
try:
s = os.stat(filename)
except FileNotFoundError:
summary = "does not exist"
except Exception as e:
summary = f"error: {e}"
else:
mod = datetime.datetime.fromtimestamp(s.st_mtime)
summary = f"{s.st_size} bytes, modified {mod}"
return summary
def short_stack(
skip: int = 0,
full: bool = False,
frame_ids: bool = False,
short_filenames: bool = False,
) -> str:
"""Return a string summarizing the call stack.
The string is multi-line, with one line per stack frame. Each line shows
the function name, the file name, and the line number:
...
start_import_stop : /Users/ned/coverage/trunk/tests/coveragetest.py:95
import_local_file : /Users/ned/coverage/trunk/tests/coveragetest.py:81
import_local_file : /Users/ned/coverage/trunk/coverage/backward.py:159
...
`skip` is the number of closest immediate frames to skip, so that debugging
functions can call this and not be included in the result.
If `full` is true, then include all frames. Otherwise, initial "boring"
frames (ones in site-packages and earlier) are omitted.
`short_filenames` will shorten filenames using `short_filename`, to reduce
the amount of repetitive noise in stack traces.
"""
# Regexes in initial frames that we don't care about.
# fmt: off
BORING_PRELUDE = [
"", # pytest-xdist has string execution.
r"\bigor.py$", # Our test runner.
r"\bsite-packages\b", # pytest etc getting to our tests.
]
# fmt: on
stack: Iterable[inspect.FrameInfo] = inspect.stack()[:skip:-1]
if not full:
for pat in BORING_PRELUDE:
stack = itertools.dropwhile(
(lambda fi, pat=pat: re.search(pat, fi.filename)), # type: ignore[misc]
stack,
)
lines = []
for frame_info in stack:
line = f"{frame_info.function:>30s} : "
if frame_ids:
line += f"{id(frame_info.frame):#x} "
filename = frame_info.filename
if short_filenames:
filename = short_filename(filename)
line += f"{filename}:{frame_info.lineno}"
lines.append(line)
return "\n".join(lines)
def dump_stack_frames(out: TWritable, skip: int = 0) -> None:
"""Print a summary of the stack to `out`."""
out.write(short_stack(skip=skip + 1) + "\n")
def clipped_repr(text: str, numchars: int = 50) -> str:
"""`repr(text)`, but limited to `numchars`."""
r = reprlib.Repr()
r.maxstring = numchars
return r.repr(text)
def short_id(id64: int) -> int:
"""Given a 64-bit id, make a shorter 16-bit one."""
id16 = 0
for offset in range(0, 64, 16):
id16 ^= id64 >> offset
return id16 & 0xFFFF
def add_pid_and_tid(text: str) -> str:
"""A filter to add pid and tid to debug messages."""
# Thread ids are useful, but too long. Make a shorter one.
tid = f"{short_id(_thread.get_ident()):04x}"
text = f"{os.getpid():5d}.{tid}: {text}"
return text
AUTO_REPR_IGNORE = {"$coverage.object_id"}
def auto_repr(self: Any) -> str:
"""A function implementing an automatic __repr__ for debugging."""
show_attrs = (
(k, v)
for k, v in self.__dict__.items()
if getattr(v, "show_repr_attr", True)
and not inspect.ismethod(v)
and k not in AUTO_REPR_IGNORE
)
return "<{klass} @{id:#x}{attrs}>".format(
klass=self.__class__.__name__,
id=id(self),
attrs="".join(f" {k}={v!r}" for k, v in show_attrs),
)
def simplify(v: Any) -> Any: # pragma: debugging
"""Turn things which are nearly dict/list/etc into dict/list/etc."""
if isinstance(v, dict):
return {k: simplify(vv) for k, vv in v.items()}
elif isinstance(v, (list, tuple)):
return type(v)(simplify(vv) for vv in v)
elif hasattr(v, "__dict__"):
return simplify({"." + k: v for k, v in v.__dict__.items()})
else:
return v
def pp(v: Any) -> None: # pragma: debugging
"""Debug helper to pretty-print data, including SimpleNamespace objects."""
# Might not be needed in 3.9+
pprint.pprint(simplify(v))
def filter_text(text: str, filters: Iterable[Callable[[str], str]]) -> str:
"""Run `text` through a series of filters.
`filters` is a list of functions. Each takes a string and returns a
string. Each is run in turn. After each filter, the text is split into
lines, and each line is passed through the next filter.
Returns: the final string that results after all of the filters have
run.
"""
clean_text = text.rstrip()
ending = text[len(clean_text) :]
text = clean_text
for filter_fn in filters:
lines = []
for line in text.splitlines():
lines.extend(filter_fn(line).splitlines())
text = "\n".join(lines)
return text + ending
class CwdTracker:
"""A class to add cwd info to debug messages."""
def __init__(self) -> None:
self.cwd: str | None = None
def filter(self, text: str) -> str:
"""Add a cwd message for each new cwd."""
cwd = os.getcwd()
if cwd != self.cwd:
text = f"cwd is now {cwd!r}\n{text}"
self.cwd = cwd
return text
class ProcessTracker:
"""Track process creation for debug logging."""
def __init__(self) -> None:
self.pid: int = os.getpid()
self.did_welcome = False
def filter(self, text: str) -> str:
"""Add a message about how new processes came to be."""
welcome = ""
pid = os.getpid()
if self.pid != pid:
welcome = f"New process: forked {self.pid} -> {pid}\n"
self.pid = pid
elif not self.did_welcome:
argv = getattr(sys, "argv", None)
welcome = (
f"New process: {pid=}, executable: {sys.executable!r}\n"
+ f"New process: cmd: {argv!r}\n"
+ f"New process parent pid: {os.getppid()!r}\n"
)
if welcome:
self.did_welcome = True
return welcome + text
else:
return text
class PytestTracker:
"""Track the current pytest test name to add to debug messages."""
def __init__(self) -> None:
self.test_name: str | None = None
def filter(self, text: str) -> str:
"""Add a message when the pytest test changes."""
test_name = os.getenv("PYTEST_CURRENT_TEST")
if test_name != self.test_name:
text = f"Pytest context: {test_name}\n{text}"
self.test_name = test_name
return text
class DebugOutputFile:
"""A file-like object that includes pid and cwd information."""
def __init__(
self,
outfile: IO[str] | None,
filters: Iterable[Callable[[str], str]],
):
self.outfile = outfile
self.filters = list(filters)
self.pid = os.getpid()
@classmethod
def get_one(
cls,
fileobj: IO[str] | None = None,
file_name: str | None = None,
filters: Iterable[Callable[[str], str]] = (),
interim: bool = False,
) -> DebugOutputFile:
"""Get a DebugOutputFile.
If `fileobj` is provided, then a new DebugOutputFile is made with it.
If `fileobj` isn't provided, then a file is chosen (`file_name` if
provided, or COVERAGE_DEBUG_FILE, or stderr), and a process-wide
singleton DebugOutputFile is made.
`filters` are the text filters to apply to the stream to annotate with
pids, etc.
If `interim` is true, then a future `get_one` can replace this one.
"""
if fileobj is not None:
# Make DebugOutputFile around the fileobj passed.
return cls(fileobj, filters)
the_one, is_interim = cls._get_singleton_data()
if the_one is None or is_interim:
if file_name is not None:
fileobj = open(file_name, "a", encoding="utf-8")
else:
# $set_env.py: COVERAGE_DEBUG_FILE - Where to write debug output
file_name = os.getenv("COVERAGE_DEBUG_FILE", FORCED_DEBUG_FILE)
if file_name in ["stdout", "stderr"]:
fileobj = getattr(sys, file_name)
elif file_name:
fileobj = open(file_name, "a", encoding="utf-8")
atexit.register(fileobj.close)
else:
fileobj = sys.stderr
the_one = cls(fileobj, filters)
cls._set_singleton_data(the_one, interim)
if not (the_one.filters):
the_one.filters = list(filters)
return the_one
# Because of the way igor.py deletes and re-imports modules,
# this class can be defined more than once. But we really want
# a process-wide singleton. So stash it in sys.modules instead of
# on a class attribute. Yes, this is aggressively gross.
SYS_MOD_NAME: Final[str] = "$coverage.debug.DebugOutputFile.the_one"
SINGLETON_ATTR: Final[str] = "the_one_and_is_interim"
@classmethod
def _set_singleton_data(cls, the_one: DebugOutputFile, interim: bool) -> None:
"""Set the one DebugOutputFile to rule them all."""
singleton_module = types.ModuleType(cls.SYS_MOD_NAME)
setattr(singleton_module, cls.SINGLETON_ATTR, (the_one, interim))
sys.modules[cls.SYS_MOD_NAME] = singleton_module
@classmethod
def _get_singleton_data(cls) -> tuple[DebugOutputFile | None, bool]:
"""Get the one DebugOutputFile."""
singleton_module = sys.modules.get(cls.SYS_MOD_NAME)
return getattr(singleton_module, cls.SINGLETON_ATTR, (None, True))
@classmethod
def _del_singleton_data(cls) -> None:
"""Delete the one DebugOutputFile, just for tests to use."""
if cls.SYS_MOD_NAME in sys.modules:
del sys.modules[cls.SYS_MOD_NAME]
def write(self, text: str) -> None:
"""Just like file.write, but filter through all our filters."""
assert self.outfile is not None
if not self.outfile.closed:
self.outfile.write(filter_text(text, self.filters))
self.outfile.flush()
def flush(self) -> None:
"""Flush our file."""
assert self.outfile is not None
if not self.outfile.closed:
self.outfile.flush()
def log(msg: str, stack: bool = False) -> None: # pragma: debugging
"""Write a log message as forcefully as possible."""
out = DebugOutputFile.get_one(interim=True)
out.write(msg + "\n")
if stack:
dump_stack_frames(out=out, skip=1)
def decorate_methods(
decorator: Callable[..., Any],
butnot: Iterable[str] = (),
private: bool = False,
) -> Callable[..., Any]: # pragma: debugging
"""A class decorator to apply a decorator to methods."""
def _decorator(cls): # type: ignore[no-untyped-def]
for name, meth in inspect.getmembers(cls, inspect.isroutine):
if name not in cls.__dict__:
continue
if name != "__init__":
if not private and name.startswith("_"):
continue
if name in butnot:
continue
setattr(cls, name, decorator(meth))
return cls
return _decorator
def break_in_pudb(func: AnyCallable) -> AnyCallable: # pragma: debugging
"""A function decorator to stop in the debugger for each call."""
@functools.wraps(func)
def _wrapper(*args: Any, **kwargs: Any) -> Any:
import pudb
sys.stdout = sys.__stdout__
pudb.set_trace()
return func(*args, **kwargs)
return _wrapper
OBJ_IDS = itertools.count()
CALLS = itertools.count()
OBJ_ID_ATTR = "$coverage.object_id"
def show_calls(
show_args: bool = True,
show_stack: bool = False,
show_return: bool = False,
) -> Callable[..., Any]: # pragma: debugging
"""A method decorator to debug-log each call to the function."""
def _decorator(func: AnyCallable) -> AnyCallable:
@functools.wraps(func)
def _wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
oid = getattr(self, OBJ_ID_ATTR, None)
if oid is None:
oid = f"{os.getpid():08d} {next(OBJ_IDS):04d}"
setattr(self, OBJ_ID_ATTR, oid)
extra = ""
if show_args:
eargs = ", ".join(map(repr, args))
ekwargs = ", ".join("{}={!r}".format(*item) for item in kwargs.items())
extra += "("
extra += eargs
if eargs and ekwargs:
extra += ", "
extra += ekwargs
extra += ")"
if show_stack:
extra += " @ "
extra += "; ".join(short_stack(short_filenames=True).splitlines())
callid = next(CALLS)
msg = f"{oid} {callid:04d} {func.__name__}{extra}\n"
DebugOutputFile.get_one(interim=True).write(msg)
ret = func(self, *args, **kwargs)
if show_return:
msg = f"{oid} {callid:04d} {func.__name__} return {ret!r}\n"
DebugOutputFile.get_one(interim=True).write(msg)
return ret
return _wrapper
return _decorator
def relevant_environment_display(env: Mapping[str, str]) -> list[tuple[str, str]]:
"""Filter environment variables for a debug display.
Select variables to display (with COV or PY in the name, or HOME, TEMP, or
TMP), and also cloak sensitive values with asterisks.
Arguments:
env: a dict of environment variable names and values.
Returns:
A list of pairs (name, value) to show.
"""
SLUGS = {"COV", "PY"}
INCLUDE = {"HOME", "TEMP", "TMP"}
CLOAK = {"API", "TOKEN", "KEY", "SECRET", "PASS", "SIGNATURE"}
TRUNCATE = {"COVERAGE_PROCESS_CONFIG"}
TRUNCATE_LEN = 60
to_show = []
for name, val in env.items():
show = False
if name in INCLUDE:
show = True
elif any(slug in name for slug in SLUGS):
show = True
if show:
if any(slug in name for slug in CLOAK):
val = re.sub(r"\w", "*", val)
if name in TRUNCATE:
if len(val) > TRUNCATE_LEN:
val = val[: TRUNCATE_LEN - 3] + "..."
to_show.append((name, val))
return human_sorted_items(to_show)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/disposition.py 0000644 0001751 0001751 00000003547 15073731535 017574 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Simple value objects for tracking what to do with files."""
from __future__ import annotations
from typing import TYPE_CHECKING
from coverage.types import TFileDisposition
if TYPE_CHECKING:
from coverage.plugin import FileTracer
class FileDisposition:
"""A simple value type for recording what to do with a file."""
original_filename: str
canonical_filename: str
source_filename: str | None
trace: bool
reason: str
file_tracer: FileTracer | None
has_dynamic_filename: bool
def __repr__(self) -> str:
return f""
# FileDisposition "methods": FileDisposition is a pure value object, so it can
# be implemented in either C or Python. Acting on them is done with these
# functions.
def disposition_init(cls: type[TFileDisposition], original_filename: str) -> TFileDisposition:
"""Construct and initialize a new FileDisposition object."""
disp = cls()
disp.original_filename = original_filename
disp.canonical_filename = original_filename
disp.source_filename = None
disp.trace = False
disp.reason = ""
disp.file_tracer = None
disp.has_dynamic_filename = False
return disp
def disposition_debug_msg(disp: TFileDisposition) -> str:
"""Make a nice debug message of what the FileDisposition is doing."""
if disp.trace:
msg = f"Tracing {disp.original_filename!r}"
if disp.original_filename != disp.source_filename:
msg += f" as {disp.source_filename!r}"
if disp.file_tracer:
msg += f": will be traced by {disp.file_tracer!r}"
else:
msg = f"Not tracing {disp.original_filename!r}: {disp.reason}"
return msg
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/env.py 0000644 0001751 0001751 00000011552 15073731535 016013 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Determine facts about the environment."""
from __future__ import annotations
import os
import platform
import sys
from collections.abc import Iterable
from typing import Any, Final
# debug_info() at the bottom wants to show all the globals, but not imports.
# Grab the global names here to know which names to not show. Nothing defined
# above this line will be in the output.
_UNINTERESTING_GLOBALS = list(globals())
# These names also shouldn't be shown.
_UNINTERESTING_GLOBALS += ["PYBEHAVIOR", "debug_info"]
# Operating systems.
WINDOWS = sys.platform == "win32"
LINUX = sys.platform.startswith("linux")
MACOS = sys.platform == "darwin"
# Python implementations.
CPYTHON = (platform.python_implementation() == "CPython") # fmt: skip
PYPY = (platform.python_implementation() == "PyPy") # fmt: skip
# Python versions. We amend version_info with one more value, a zero if an
# official version, or 1 if built from source beyond an official version.
# Only use sys.version_info directly where tools like mypy need it to understand
# version-specfic code, otherwise use PYVERSION.
PYVERSION = sys.version_info + (int(platform.python_version()[-1] == "+"),)
if PYPY:
# Minimum now is 7.3.16
PYPYVERSION = tuple(sys.pypy_version_info) # type: ignore[attr-defined]
else:
PYPYVERSION = (0,)
# Do we have a GIL?
GIL = getattr(sys, "_is_gil_enabled", lambda: True)()
# Do we ship compiled coveragepy wheels for this version?
SHIPPING_WHEELS = CPYTHON and PYVERSION[:2] <= (3, 14)
# Should we default to sys.monitoring?
SYSMON_DEFAULT = CPYTHON and PYVERSION >= (3, 14)
# Python behavior.
class PYBEHAVIOR:
"""Flags indicating this Python's behavior."""
# When leaving a with-block, do we visit the with-line exactly,
# or the context managers in inner-out order?
#
# mwith.py:
# with (
# open("/tmp/one", "w") as f2,
# open("/tmp/two", "w") as f3,
# open("/tmp/three", "w") as f4,
# ):
# print("hello 6")
#
# % python3.11 -m trace -t mwith.py | grep mwith
# --- modulename: mwith, funcname:
# mwith.py(2): open("/tmp/one", "w") as f2,
# mwith.py(1): with (
# mwith.py(2): open("/tmp/one", "w") as f2,
# mwith.py(3): open("/tmp/two", "w") as f3,
# mwith.py(1): with (
# mwith.py(3): open("/tmp/two", "w") as f3,
# mwith.py(4): open("/tmp/three", "w") as f4,
# mwith.py(1): with (
# mwith.py(4): open("/tmp/three", "w") as f4,
# mwith.py(6): print("hello 6")
# mwith.py(1): with (
#
# % python3.12 -m trace -t mwith.py | grep mwith
# --- modulename: mwith, funcname:
# mwith.py(2): open("/tmp/one", "w") as f2,
# mwith.py(3): open("/tmp/two", "w") as f3,
# mwith.py(4): open("/tmp/three", "w") as f4,
# mwith.py(6): print("hello 6")
# mwith.py(4): open("/tmp/three", "w") as f4,
# mwith.py(3): open("/tmp/two", "w") as f3,
# mwith.py(2): open("/tmp/one", "w") as f2,
exit_with_through_ctxmgr = (PYVERSION >= (3, 12, 6)) # fmt: skip
# f-strings are parsed as code, pep 701
fstring_syntax = (PYVERSION >= (3, 12)) # fmt: skip
# PEP669 Low Impact Monitoring: https://peps.python.org/pep-0669/
pep669: Final[bool] = bool(getattr(sys, "monitoring", None))
# Where does frame.f_lasti point when yielding from a generator?
# It used to point at the YIELD, in 3.13 it points at the RESUME,
# then it went back to the YIELD.
# https://github.com/python/cpython/issues/113728
lasti_is_yield = (PYVERSION[:2] != (3, 13)) # fmt: skip
# PEP649 and PEP749: Deferred annotations
deferred_annotations = (PYVERSION >= (3, 14)) # fmt: skip
# Does sys.monitoring support BRANCH_RIGHT and BRANCH_LEFT? The names
# were added in early 3.14 alphas, but didn't work entirely correctly until
# after 3.14.0a5.
branch_right_left = pep669 and (PYVERSION > (3, 14, 0, "alpha", 5, 0))
# Coverage.py specifics, about testing scenarios. See tests/testenv.py also.
# Are we coverage-measuring ourselves?
METACOV = os.getenv("COVERAGE_COVERAGE") is not None
# Are we running our test suite?
# Even when running tests, you can use COVERAGE_TESTING=0 to disable the
# test-specific behavior like AST checking.
TESTING = os.getenv("COVERAGE_TESTING") == "True"
def debug_info() -> Iterable[tuple[str, Any]]:
"""Return a list of (name, value) pairs for printing debug information."""
info = [
(name, value)
for name, value in globals().items()
if not name.startswith("_") and name not in _UNINTERESTING_GLOBALS
]
info += [
(name, value) for name, value in PYBEHAVIOR.__dict__.items() if not name.startswith("_")
]
return sorted(info)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/exceptions.py 0000644 0001751 0001751 00000002624 15073731535 017404 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Exceptions coverage.py can raise."""
from __future__ import annotations
from typing import Any
class CoverageException(Exception):
"""The base class of all exceptions raised by Coverage.py."""
def __init__(self, *args: Any, slug: str | None = None) -> None:
super().__init__(*args)
self.slug = slug
class ConfigError(CoverageException):
"""A problem with a config file, or a value in one."""
pass
class DataError(CoverageException):
"""An error in using a data file."""
pass
class NoDataError(CoverageException):
"""We didn't have data to work with."""
pass
class NoSource(CoverageException):
"""We couldn't find the source for a module."""
pass
class NoCode(NoSource):
"""We couldn't find any code at all."""
pass
class NotPython(CoverageException):
"""A source file turned out not to be parsable Python."""
pass
class PluginError(CoverageException):
"""A plugin misbehaved."""
pass
class _ExceptionDuringRun(CoverageException):
"""An exception happened while running customer code.
Construct it with three arguments, the values from `sys.exc_info`.
"""
pass
class CoverageWarning(Warning):
"""A warning from Coverage.py."""
pass
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/execfile.py 0000644 0001751 0001751 00000027327 15073731535 017016 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Execute files of Python code."""
from __future__ import annotations
import importlib.machinery
import importlib.util
import inspect
import marshal
import os
import struct
import sys
from importlib.machinery import ModuleSpec
from types import CodeType, ModuleType
from typing import Any
from coverage.exceptions import CoverageException, NoCode, NoSource, _ExceptionDuringRun
from coverage.files import canonical_filename, python_reported_file
from coverage.misc import isolate_module
from coverage.python import get_python_source
os = isolate_module(os)
PYC_MAGIC_NUMBER = importlib.util.MAGIC_NUMBER
class DummyLoader:
"""A shim for the pep302 __loader__, emulating pkgutil.ImpLoader.
Currently only implements the .fullname attribute
"""
def __init__(self, fullname: str, *_args: Any) -> None:
self.fullname = fullname
def find_module(
modulename: str,
) -> tuple[str | None, str, ModuleSpec]:
"""Find the module named `modulename`.
Returns the file path of the module, the name of the enclosing
package, and the spec.
"""
try:
spec = importlib.util.find_spec(modulename)
except ImportError as err:
raise NoSource(str(err)) from err
if not spec:
raise NoSource(f"No module named {modulename!r}")
pathname = spec.origin
packagename = spec.name
if spec.submodule_search_locations:
mod_main = modulename + ".__main__"
spec = importlib.util.find_spec(mod_main)
if not spec:
raise NoSource(
f"No module named {mod_main}; "
+ f"{modulename!r} is a package and cannot be directly executed",
)
pathname = spec.origin
packagename = spec.name
packagename = packagename.rpartition(".")[0]
return pathname, packagename, spec
class PyRunner:
"""Multi-stage execution of Python code.
This is meant to emulate real Python execution as closely as possible.
"""
def __init__(self, args: list[str], as_module: bool = False) -> None:
self.args = args
self.as_module = as_module
self.arg0 = args[0]
self.package: str | None = None
self.modulename: str | None = None
self.pathname: str | None = None
self.loader: DummyLoader | None = None
self.spec: ModuleSpec | None = None
def prepare(self) -> None:
"""Set sys.path properly.
This needs to happen before any importing, and without importing anything.
"""
path0: str | None
if getattr(sys.flags, "safe_path", False):
# See https://docs.python.org/3/using/cmdline.html#cmdoption-P
path0 = None
elif self.as_module:
path0 = os.getcwd()
elif os.path.isdir(self.arg0):
# Running a directory means running the __main__.py file in that
# directory.
path0 = self.arg0
else:
path0 = os.path.abspath(os.path.dirname(self.arg0))
if os.path.isdir(sys.path[0]):
# sys.path fakery. If we are being run as a command, then sys.path[0]
# is the directory of the "coverage" script. If this is so, replace
# sys.path[0] with the directory of the file we're running, or the
# current directory when running modules. If it isn't so, then we
# don't know what's going on, and just leave it alone.
top_file = inspect.stack()[-1][0].f_code.co_filename
sys_path_0_abs = os.path.abspath(sys.path[0])
top_file_dir_abs = os.path.abspath(os.path.dirname(top_file))
sys_path_0_abs = canonical_filename(sys_path_0_abs)
top_file_dir_abs = canonical_filename(top_file_dir_abs)
if sys_path_0_abs != top_file_dir_abs:
path0 = None
else:
# sys.path[0] is a file. Is the next entry the directory containing
# that file?
if sys.path[1] == os.path.dirname(sys.path[0]):
# Can it be right to always remove that?
del sys.path[1]
if path0 is not None:
sys.path[0] = python_reported_file(path0)
def _prepare2(self) -> None:
"""Do more preparation to run Python code.
Includes finding the module to run and adjusting sys.argv[0].
This method is allowed to import code.
"""
if self.as_module:
self.modulename = self.arg0
pathname, self.package, self.spec = find_module(self.modulename)
if self.spec is not None:
self.modulename = self.spec.name
self.loader = DummyLoader(self.modulename)
assert pathname is not None
self.pathname = os.path.abspath(pathname)
self.args[0] = self.arg0 = self.pathname
elif os.path.isdir(self.arg0):
# Running a directory means running the __main__.py file in that
# directory.
for ext in [".py", ".pyc", ".pyo"]:
try_filename = os.path.join(self.arg0, f"__main__{ext}")
# 3.8.10 changed how files are reported when running a
# directory.
try_filename = os.path.abspath(try_filename)
if os.path.exists(try_filename):
self.arg0 = try_filename
break
else:
raise NoSource(f"Can't find '__main__' module in '{self.arg0}'")
# Make a spec. I don't know if this is the right way to do it.
try_filename = python_reported_file(try_filename)
self.spec = importlib.machinery.ModuleSpec("__main__", None, origin=try_filename)
self.spec.has_location = True
self.package = ""
self.loader = DummyLoader("__main__")
else:
self.loader = DummyLoader("__main__")
self.arg0 = python_reported_file(self.arg0)
def run(self) -> None:
"""Run the Python code!"""
self._prepare2()
# Create a module to serve as __main__
main_mod = ModuleType("__main__")
from_pyc = self.arg0.endswith((".pyc", ".pyo"))
main_mod.__file__ = self.arg0
if from_pyc:
main_mod.__file__ = main_mod.__file__[:-1]
if self.package is not None:
main_mod.__package__ = self.package
main_mod.__loader__ = self.loader # type: ignore[assignment]
if self.spec is not None:
main_mod.__spec__ = self.spec
main_mod.__builtins__ = sys.modules["builtins"] # type: ignore[attr-defined]
sys.modules["__main__"] = main_mod
# Set sys.argv properly.
sys.argv = self.args
try:
# Make a code object somehow.
if from_pyc:
code = make_code_from_pyc(self.arg0)
else:
code = make_code_from_py(self.arg0)
except CoverageException:
raise
except Exception as exc:
msg = f"Couldn't run '{self.arg0}' as Python code: {exc.__class__.__name__}: {exc}"
raise CoverageException(msg) from exc
# Execute the code object.
# Return to the original directory in case the test code exits in
# a non-existent directory.
cwd = os.getcwd()
try:
exec(code, main_mod.__dict__)
except SystemExit: # pylint: disable=try-except-raise
# The user called sys.exit(). Just pass it along to the upper
# layers, where it will be handled.
raise
except Exception:
# Something went wrong while executing the user code.
# Get the exc_info, and pack them into an exception that we can
# throw up to the outer loop. We peel one layer off the traceback
# so that the coverage.py code doesn't appear in the final printed
# traceback.
typ, err, tb = sys.exc_info()
assert typ is not None
assert err is not None
assert tb is not None
# PyPy3 weirdness. If I don't access __context__, then somehow it
# is non-None when the exception is reported at the upper layer,
# and a nested exception is shown to the user. This getattr fixes
# it somehow? https://bitbucket.org/pypy/pypy/issue/1903
getattr(err, "__context__", None)
# Call the excepthook.
try:
assert err.__traceback__ is not None
err.__traceback__ = err.__traceback__.tb_next
sys.excepthook(typ, err, tb.tb_next)
except SystemExit: # pylint: disable=try-except-raise
raise
except Exception as exc:
# Getting the output right in the case of excepthook
# shenanigans is kind of involved.
sys.stderr.write("Error in sys.excepthook:\n")
typ2, err2, tb2 = sys.exc_info()
assert typ2 is not None
assert err2 is not None
assert tb2 is not None
err2.__suppress_context__ = True
assert err2.__traceback__ is not None
err2.__traceback__ = err2.__traceback__.tb_next
sys.__excepthook__(typ2, err2, tb2.tb_next)
sys.stderr.write("\nOriginal exception was:\n")
raise _ExceptionDuringRun(typ, err, tb.tb_next) from exc
else:
sys.exit(1)
finally:
os.chdir(cwd)
def run_python_module(args: list[str]) -> None:
"""Run a Python module, as though with ``python -m name args...``.
`args` is the argument array to present as sys.argv, including the first
element naming the module being executed.
This is a helper for tests, to encapsulate how to use PyRunner.
"""
runner = PyRunner(args, as_module=True)
runner.prepare()
runner.run()
def run_python_file(args: list[str]) -> None:
"""Run a Python file as if it were the main program on the command line.
`args` is the argument array to present as sys.argv, including the first
element naming the file being executed. `package` is the name of the
enclosing package, if any.
This is a helper for tests, to encapsulate how to use PyRunner.
"""
runner = PyRunner(args, as_module=False)
runner.prepare()
runner.run()
def make_code_from_py(filename: str) -> CodeType:
"""Get source from `filename` and make a code object of it."""
try:
source = get_python_source(filename)
except (OSError, NoSource) as exc:
raise NoSource(f"No file to run: '{filename}'") from exc
code = compile(source, filename, mode="exec", dont_inherit=True)
return code
def make_code_from_pyc(filename: str) -> CodeType:
"""Get a code object from a .pyc file."""
try:
fpyc = open(filename, "rb")
except OSError as exc:
raise NoCode(f"No file to run: '{filename}'") from exc
with fpyc:
# First four bytes are a version-specific magic number. It has to
# match or we won't run the file.
magic = fpyc.read(4)
if magic != PYC_MAGIC_NUMBER:
raise NoCode(f"Bad magic number in .pyc file: {magic!r} != {PYC_MAGIC_NUMBER!r}")
flags = struct.unpack(" None:
"""Set the directory that `relative_filename` will be relative to."""
global RELATIVE_DIR, CANONICAL_FILENAME_CACHE
# The current directory
abs_curdir = abs_file(os.curdir)
if not abs_curdir.endswith(os.sep):
# Suffix with separator only if not at the system root
abs_curdir = abs_curdir + os.sep
# The absolute path to our current directory.
RELATIVE_DIR = os.path.normcase(abs_curdir)
# Cache of results of calling the canonical_filename() method, to
# avoid duplicating work.
CANONICAL_FILENAME_CACHE = {}
def relative_directory() -> str:
"""Return the directory that `relative_filename` is relative to."""
return RELATIVE_DIR
def relative_filename(filename: str) -> str:
"""Return the relative form of `filename`.
The file name will be relative to the current directory when the
`set_relative_directory` was called.
"""
fnorm = os.path.normcase(filename)
if fnorm.startswith(RELATIVE_DIR):
filename = filename[len(RELATIVE_DIR) :]
return filename
def canonical_filename(filename: str) -> str:
"""Return a canonical file name for `filename`.
An absolute path with no redundant components and normalized case.
"""
if filename not in CANONICAL_FILENAME_CACHE:
cf = filename
if not os.path.isabs(filename):
for path in [os.curdir] + sys.path:
if path is None:
continue # type: ignore[unreachable]
f = os.path.join(path, filename)
try:
exists = os.path.exists(f)
except UnicodeError:
exists = False
if exists:
cf = f
break
cf = abs_file(cf)
CANONICAL_FILENAME_CACHE[filename] = cf
return CANONICAL_FILENAME_CACHE[filename]
def flat_rootname(filename: str) -> str:
"""A base for a flat file name to correspond to this file.
Useful for writing files about the code where you want all the files in
the same directory, but need to differentiate same-named files from
different directories.
For example, the file a/b/c.py will return 'z_86bbcbe134d28fd2_c_py'
"""
dirname, basename = ntpath.split(filename)
if dirname:
fp = hashlib.new(
"sha3_256",
dirname.encode("UTF-8"),
usedforsecurity=False,
).hexdigest()[:16]
prefix = f"z_{fp}_"
else:
prefix = ""
return prefix + basename.replace(".", "_")
if env.WINDOWS:
_ACTUAL_PATH_CACHE: dict[str, str] = {}
_ACTUAL_PATH_LIST_CACHE: dict[str, list[str]] = {}
def actual_path(path: str) -> str:
"""Get the actual path of `path`, including the correct case."""
if path in _ACTUAL_PATH_CACHE:
return _ACTUAL_PATH_CACHE[path]
head, tail = os.path.split(path)
if not tail:
# This means head is the drive spec: normalize it.
actpath = head.upper()
elif not head:
actpath = tail
else:
head = actual_path(head)
if head in _ACTUAL_PATH_LIST_CACHE:
files = _ACTUAL_PATH_LIST_CACHE[head]
else:
try:
files = os.listdir(head)
except Exception:
# This will raise OSError, or this bizarre TypeError:
# https://bugs.python.org/issue1776160
files = []
_ACTUAL_PATH_LIST_CACHE[head] = files
normtail = os.path.normcase(tail)
for f in files:
if os.path.normcase(f) == normtail:
tail = f
break
actpath = os.path.join(head, tail)
_ACTUAL_PATH_CACHE[path] = actpath
return actpath
else:
def actual_path(path: str) -> str:
"""The actual path for non-Windows platforms."""
return path
def abs_file(path: str) -> str:
"""Return the absolute normalized form of `path`."""
return actual_path(os.path.abspath(os.path.realpath(path)))
def zip_location(filename: str) -> tuple[str, str] | None:
"""Split a filename into a zipfile / inner name pair.
Only return a pair if the zipfile exists. No check is made if the inner
name is in the zipfile.
"""
for ext in [".zip", ".whl", ".egg", ".pex", ".par"]:
zipbase, extension, inner = filename.partition(ext + sep(filename))
if extension:
zipfile = zipbase + ext
if os.path.exists(zipfile):
return zipfile, inner
return None
def source_exists(path: str) -> bool:
"""Determine if a source file path exists."""
if os.path.exists(path):
return True
if zip_location(path):
# If zip_location returns anything, then it's a zipfile that
# exists. That's good enough for us.
return True
return False
def python_reported_file(filename: str) -> str:
"""Return the string as Python would describe this file name."""
return os.path.abspath(filename)
def isabs_anywhere(filename: str) -> bool:
"""Is `filename` an absolute path on any OS?"""
return ntpath.isabs(filename) or posixpath.isabs(filename)
def prep_patterns(patterns: Iterable[str]) -> list[str]:
"""Prepare the file patterns for use in a `GlobMatcher`.
If a pattern starts with a wildcard, it is used as a pattern
as-is. If it does not start with a wildcard, then it is made
absolute with the current directory.
If `patterns` is None, an empty list is returned.
"""
prepped = []
for p in patterns or []:
prepped.append(p)
if not p.startswith(("*", "?")):
prepped.append(abs_file(p))
return prepped
class TreeMatcher:
"""A matcher for files in a tree.
Construct with a list of paths, either files or directories. Paths match
with the `match` method if they are one of the files, or if they are
somewhere in a subtree rooted at one of the directories.
"""
def __init__(self, paths: Iterable[str], name: str = "unknown") -> None:
self.original_paths: list[str] = human_sorted(paths)
self.paths = [os.path.normcase(p) for p in paths]
self.name = name
def __repr__(self) -> str:
return f""
def info(self) -> list[str]:
"""A list of strings for displaying when dumping state."""
return self.original_paths
def match(self, fpath: str) -> bool:
"""Does `fpath` indicate a file in one of our trees?"""
fpath = os.path.normcase(fpath)
for p in self.paths:
if fpath.startswith(p):
if fpath == p:
# This is the same file!
return True
if fpath[len(p)] == os.sep:
# This is a file in the directory
return True
return False
class ModuleMatcher:
"""A matcher for modules in a tree."""
def __init__(self, module_names: Iterable[str], name: str = "unknown") -> None:
self.modules = list(module_names)
self.name = name
def __repr__(self) -> str:
return f""
def info(self) -> list[str]:
"""A list of strings for displaying when dumping state."""
return self.modules
def match(self, module_name: str) -> bool:
"""Does `module_name` indicate a module in one of our packages?"""
if not module_name:
return False
for m in self.modules:
if module_name.startswith(m):
if module_name == m:
return True
if module_name[len(m)] == ".":
# This is a module in the package
return True
return False
class GlobMatcher:
"""A matcher for files by file name pattern."""
def __init__(self, pats: Iterable[str], name: str = "unknown") -> None:
self.pats = list(pats)
self.re = globs_to_regex(self.pats, case_insensitive=env.WINDOWS)
self.name = name
def __repr__(self) -> str:
return f""
def info(self) -> list[str]:
"""A list of strings for displaying when dumping state."""
return self.pats
def match(self, fpath: str) -> bool:
"""Does `fpath` match one of our file name patterns?"""
return self.re.match(fpath) is not None
def sep(s: str) -> str:
"""Find the path separator used in this string, or os.sep if none."""
if sep_match := re.search(r"[\\/]", s):
the_sep = sep_match[0]
else:
the_sep = os.sep
return the_sep
# Tokenizer for _glob_to_regex.
# None as a sub means disallowed.
# fmt: off
G2RX_TOKENS = [(re.compile(rx), sub) for rx, sub in [
(r"\*\*\*+", None), # Can't have ***
(r"[^/]+\*\*+", None), # Can't have x**
(r"\*\*+[^/]+", None), # Can't have **x
(r"\*\*/\*\*", None), # Can't have **/**
(r"^\*+/", r"(.*[/\\\\])?"), # ^*/ matches any prefix-slash, or nothing.
(r"/\*+$", r"[/\\\\].*"), # /*$ matches any slash-suffix.
(r"\*\*/", r"(.*[/\\\\])?"), # **/ matches any subdirs, including none
(r"/", r"[/\\\\]"), # / matches either slash or backslash
(r"\*", r"[^/\\\\]*"), # * matches any number of non slash-likes
(r"\?", r"[^/\\\\]"), # ? matches one non slash-like
(r"\[.*?\]", r"\g<0>"), # [a-f] matches [a-f]
(r"[a-zA-Z0-9_-]+", r"\g<0>"), # word chars match themselves
(r"[\[\]]", None), # Can't have single square brackets
(r".", r"\\\g<0>"), # Anything else is escaped to be safe
]]
# fmt: on
def _glob_to_regex(pattern: str) -> str:
"""Convert a file-path glob pattern into a regex."""
# Turn all backslashes into slashes to simplify the tokenizer.
pattern = pattern.replace("\\", "/")
if "/" not in pattern:
pattern = f"**/{pattern}"
path_rx = []
pos = 0
while pos < len(pattern):
for rx, sub in G2RX_TOKENS: # pragma: always breaks
if m := rx.match(pattern, pos=pos):
if sub is None:
raise ConfigError(f"File pattern can't include {m[0]!r}")
path_rx.append(m.expand(sub))
pos = m.end()
break
return "".join(path_rx)
def globs_to_regex(
patterns: Iterable[str],
case_insensitive: bool = False,
partial: bool = False,
) -> re.Pattern[str]:
"""Convert glob patterns to a compiled regex that matches any of them.
Slashes are always converted to match either slash or backslash, for
Windows support, even when running elsewhere.
If the pattern has no slash or backslash, then it is interpreted as
matching a file name anywhere it appears in the tree. Otherwise, the glob
pattern must match the whole file path.
If `partial` is true, then the pattern will match if the target string
starts with the pattern. Otherwise, it must match the entire string.
Returns: a compiled regex object. Use the .match method to compare target
strings.
"""
flags = 0
if case_insensitive:
flags |= re.IGNORECASE
rx = join_regex(map(_glob_to_regex, patterns))
if not partial:
rx = rf"(?:{rx})\Z"
compiled = re.compile(rx, flags=flags)
return compiled
class PathAliases:
"""A collection of aliases for paths.
When combining data files from remote machines, often the paths to source
code are different, for example, due to OS differences, or because of
serialized checkouts on continuous integration machines.
A `PathAliases` object tracks a list of pattern/result pairs, and can
map a path through those aliases to produce a unified path.
"""
def __init__(
self,
debugfn: Callable[[str], None] | None = None,
relative: bool = False,
) -> None:
# A list of (original_pattern, regex, result)
self.aliases: list[tuple[str, re.Pattern[str], str]] = []
self.debugfn = debugfn or (lambda msg: 0)
self.relative = relative
self.pprinted = False
def pprint(self) -> None:
"""Dump the important parts of the PathAliases, for debugging."""
self.debugfn(f"Aliases (relative={self.relative}):")
for original_pattern, regex, result in self.aliases:
self.debugfn(f" Rule: {original_pattern!r} -> {result!r} using regex {regex.pattern!r}")
def add(self, pattern: str, result: str) -> None:
"""Add the `pattern`/`result` pair to the list of aliases.
`pattern` is an `glob`-style pattern. `result` is a simple
string. When mapping paths, if a path starts with a match against
`pattern`, then that match is replaced with `result`. This models
isomorphic source trees being rooted at different places on two
different machines.
`pattern` can't end with a wildcard component, since that would
match an entire tree, and not just its root.
"""
original_pattern = pattern
pattern_sep = sep(pattern)
if len(pattern) > 1:
pattern = pattern.rstrip(r"\/")
# The pattern can't end with a wildcard component.
if pattern.endswith("*"):
raise ConfigError("Pattern must not end with wildcards.")
# The pattern is meant to match a file path. Let's make it absolute
# unless it already is, or is meant to match any prefix.
if not self.relative:
if not pattern.startswith("*") and not isabs_anywhere(pattern + pattern_sep):
pattern = abs_file(pattern)
if not pattern.endswith(pattern_sep):
pattern += pattern_sep
# Make a regex from the pattern.
regex = globs_to_regex([pattern], case_insensitive=True, partial=True)
# Normalize the result: it must end with a path separator.
result_sep = sep(result)
result = result.rstrip(r"\/") + result_sep
self.aliases.append((original_pattern, regex, result))
def map(self, path: str, exists: Callable[[str], bool] = source_exists) -> str:
"""Map `path` through the aliases.
`path` is checked against all of the patterns. The first pattern to
match is used to replace the root of the path with the result root.
Only one pattern is ever used. If no patterns match, `path` is
returned unchanged.
The separator style in the result is made to match that of the result
in the alias.
`exists` is a function to determine if the resulting path actually
exists.
Returns the mapped path. If a mapping has happened, this is a
canonical path. If no mapping has happened, it is the original value
of `path` unchanged.
"""
if not self.pprinted:
self.pprint()
self.pprinted = True
for original_pattern, regex, result in self.aliases:
if m := regex.match(path):
new = path.replace(m[0], result)
new = new.replace(sep(path), sep(result))
if not self.relative:
new = canonical_filename(new)
dot_start = result.startswith(("./", ".\\")) and len(result) > 2
if new.startswith(("./", ".\\")) and not dot_start:
new = new[2:]
if not exists(new):
self.debugfn(
f"Rule {original_pattern!r} changed {path!r} to {new!r} "
+ "which doesn't exist, continuing",
)
continue
self.debugfn(
f"Matched path {path!r} to rule {original_pattern!r} -> {result!r}, "
+ f"producing {new!r}",
)
return new
# If we get here, no pattern matched.
if self.relative:
path = relative_filename(path)
if self.relative and not isabs_anywhere(path):
# Auto-generate a pattern to implicitly match relative files
parts = re.split(r"[/\\]", path)
if len(parts) > 1:
dir1 = parts[0]
pattern = f"*/{dir1}"
regex_pat = rf"^(.*[\\/])?{re.escape(dir1)}[\\/]"
result = f"{dir1}{os.sep}"
# Only add a new pattern if we don't already have this pattern.
if not any(p == pattern for p, _, _ in self.aliases):
self.debugfn(
f"Generating rule: {pattern!r} -> {result!r} using regex {regex_pat!r}",
)
self.aliases.append((pattern, re.compile(regex_pat), result))
return self.map(path, exists=exists)
self.debugfn(f"No rules match, path {path!r} is unchanged")
return path
def find_python_files(dirname: str, include_namespace_packages: bool) -> Iterable[str]:
"""Yield all of the importable Python files in `dirname`, recursively.
To be importable, the files have to be in a directory with a __init__.py,
except for `dirname` itself, which isn't required to have one. The
assumption is that `dirname` was specified directly, so the user knows
best, but sub-directories are checked for a __init__.py to be sure we only
find the importable files.
If `include_namespace_packages` is True, then the check for __init__.py
files is skipped.
Files with strange characters are skipped, since they couldn't have been
imported, and are probably editor side-files.
"""
for i, (dirpath, dirnames, filenames) in enumerate(os.walk(dirname)):
if not include_namespace_packages:
if i > 0 and "__init__.py" not in filenames:
# If a directory doesn't have __init__.py, then it isn't
# importable and neither are its files
del dirnames[:]
continue
for filename in filenames:
# We're only interested in files that look like reasonable Python
# files: Must end with .py or .pyw, and must not have certain funny
# characters that probably mean they are editor junk.
if re.match(r"^[^.#~!$@%^&*()+=,]+\.pyw?$", filename):
yield os.path.join(dirpath, filename)
# Globally set the relative directory.
set_relative_directory()
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/html.py 0000644 0001751 0001751 00000075226 15073731535 016177 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""HTML reporting for coverage.py."""
from __future__ import annotations
import collections
import dataclasses
import datetime
import functools
import json
import os
import re
import string
from collections.abc import Iterable
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any
import coverage
from coverage.data import CoverageData, add_data_to_hash
from coverage.exceptions import NoDataError
from coverage.files import flat_rootname
from coverage.misc import (
Hasher,
ensure_dir,
file_be_gone,
format_local_datetime,
human_sorted,
isolate_module,
plural,
stdout_link,
)
from coverage.report_core import get_analysis_to_report
from coverage.results import Analysis, AnalysisNarrower, Numbers
from coverage.templite import Templite
from coverage.types import TLineNo, TMorf
from coverage.version import __url__
if TYPE_CHECKING:
from coverage import Coverage
from coverage.plugins import FileReporter
os = isolate_module(os)
def data_filename(fname: str) -> str:
"""Return the path to an "htmlfiles" data file of ours."""
static_dir = os.path.join(os.path.dirname(__file__), "htmlfiles")
static_filename = os.path.join(static_dir, fname)
return static_filename
def read_data(fname: str) -> str:
"""Return the contents of a data file of ours."""
with open(data_filename(fname), encoding="utf-8") as data_file:
return data_file.read()
def write_html(fname: str, html: str) -> None:
"""Write `html` to `fname`, properly encoded."""
html = re.sub(r"(\A\s+)|(\s+$)", "", html, flags=re.MULTILINE) + "\n"
with open(fname, "wb") as fout:
fout.write(html.encode("ascii", "xmlcharrefreplace"))
@dataclass
class LineData:
"""The data for each source line of HTML output."""
tokens: list[tuple[str, str]]
number: TLineNo
category: str
contexts: list[str]
contexts_label: str
context_list: list[str]
short_annotations: list[str]
long_annotations: list[str]
html: str = ""
context_str: str | None = None
annotate: str | None = None
annotate_long: str | None = None
css_class: str = ""
@dataclass
class FileData:
"""The data for each source file of HTML output."""
relative_filename: str
nums: Numbers
lines: list[LineData]
@dataclass
class IndexItem:
"""Information for each index entry, to render an index page."""
url: str = ""
file: str = ""
description: str = ""
nums: Numbers = field(default_factory=Numbers)
@dataclass
class IndexPage:
"""Data for each index page."""
noun: str
plural: str
filename: str
summaries: list[IndexItem]
totals: Numbers
skipped_covered_count: int
skipped_empty_count: int
class HtmlDataGeneration:
"""Generate structured data to be turned into HTML reports."""
EMPTY = "(empty)"
def __init__(self, cov: Coverage) -> None:
self.coverage = cov
self.config = self.coverage.config
self.data = self.coverage.get_data()
self.has_arcs = self.data.has_arcs()
if self.config.show_contexts:
if self.data.measured_contexts() == {""}:
self.coverage._warn("No contexts were measured")
self.data.set_query_contexts(self.config.report_contexts)
def data_for_file(self, fr: FileReporter, analysis: Analysis) -> FileData:
"""Produce the data needed for one file's report."""
if self.has_arcs:
missing_branch_arcs = analysis.missing_branch_arcs()
arcs_executed = analysis.arcs_executed
else:
missing_branch_arcs = {}
arcs_executed = []
if self.config.show_contexts:
contexts_by_lineno = self.data.contexts_by_lineno(analysis.filename)
lines = []
branch_stats = analysis.branch_stats()
multiline_map = {}
if hasattr(fr, "multiline_map"):
multiline_map = fr.multiline_map()
for lineno, tokens in enumerate(fr.source_token_lines(), start=1):
# Figure out how to mark this line.
category = category2 = ""
short_annotations = []
long_annotations = []
if lineno in analysis.excluded:
category = "exc"
elif lineno in analysis.missing:
category = "mis"
elif self.has_arcs and lineno in missing_branch_arcs:
category = "par"
mba = missing_branch_arcs[lineno]
if len(mba) == branch_stats[lineno][0]:
# None of the branches were taken from this line.
short_annotations.append("anywhere")
long_annotations.append(
f"line {lineno} didn't jump anywhere: it always raised an exception."
)
else:
for b in missing_branch_arcs[lineno]:
if b < 0:
short_annotations.append("exit")
else:
short_annotations.append(str(b))
long_annotations.append(
fr.missing_arc_description(lineno, b, arcs_executed)
)
elif lineno in analysis.statements:
category = "run"
elif first_line := multiline_map.get(lineno):
if first_line in analysis.excluded:
category2 = "exc2"
elif first_line in analysis.missing:
category2 = "mis2"
elif self.has_arcs and first_line in missing_branch_arcs:
category2 = "par2"
# I don't understand why this last condition is marked as
# partial. If I add an else with an exception, the exception
# is raised.
elif first_line in analysis.statements: # pragma: part covered
category2 = "run2"
contexts = []
contexts_label = ""
context_list = []
if category and self.config.show_contexts:
contexts = human_sorted(c or self.EMPTY for c in contexts_by_lineno.get(lineno, ()))
if contexts == [self.EMPTY]:
contexts_label = self.EMPTY
else:
contexts_label = f"{len(contexts)} ctx"
context_list = contexts
lines.append(
LineData(
tokens=tokens,
number=lineno,
category=category or category2,
contexts=contexts,
contexts_label=contexts_label,
context_list=context_list,
short_annotations=short_annotations,
long_annotations=long_annotations,
)
)
file_data = FileData(
relative_filename=fr.relative_filename(),
nums=analysis.numbers,
lines=lines,
)
return file_data
class FileToReport:
"""A file we're considering reporting."""
def __init__(self, fr: FileReporter, analysis: Analysis) -> None:
self.fr = fr
self.analysis = analysis
self.rootname = flat_rootname(fr.relative_filename())
self.html_filename = self.rootname + ".html"
self.prev_html = self.next_html = ""
HTML_SAFE = string.ascii_letters + string.digits + "!#$%'()*+,-./:;=?@[]^_`{|}~"
@functools.cache
def encode_int(n: int) -> str:
"""Create a short HTML-safe string from an integer, using HTML_SAFE."""
if n == 0:
return HTML_SAFE[0]
r = []
while n:
n, t = divmod(n, len(HTML_SAFE))
r.append(HTML_SAFE[t])
return "".join(r)
def copy_with_cache_bust(src: str, dest_dir: str) -> str:
"""Copy `src` to `dest_dir`, adding a hash to the name.
Returns the updated destination file name with hash.
"""
with open(src, "rb") as f:
text = f.read()
h = Hasher()
h.update(text)
cache_bust = h.hexdigest()[:8]
src_base = os.path.basename(src)
dest = src_base.replace(".", f"_cb_{cache_bust}.")
with open(os.path.join(dest_dir, dest), "wb") as f:
f.write(text)
return dest
class HtmlReporter:
"""HTML reporting."""
# These files will be copied from the htmlfiles directory to the output
# directory.
STATIC_FILES = [
"style.css",
"coverage_html.js",
"keybd_closed.png",
"favicon_32.png",
]
def __init__(self, cov: Coverage) -> None:
self.coverage = cov
self.config = self.coverage.config
self.directory = self.config.html_dir
self.skip_covered = self.config.html_skip_covered
if self.skip_covered is None:
self.skip_covered = self.config.skip_covered
self.skip_empty = self.config.html_skip_empty
if self.skip_empty is None:
self.skip_empty = self.config.skip_empty
title = self.config.html_title
self.extra_css = bool(self.config.extra_css)
self.data = self.coverage.get_data()
self.has_arcs = self.data.has_arcs()
self.index_pages: dict[str, IndexPage] = {
"file": self.new_index_page("file", "files"),
}
self.incr = IncrementalChecker(self.directory)
self.datagen = HtmlDataGeneration(self.coverage)
self.directory_was_empty = False
self.first_fr = None
self.final_fr = None
self.template_globals = {
# Functions available in the templates.
"escape": escape,
"pair": pair,
"len": len,
# Constants for this report.
"__url__": __url__,
"__version__": coverage.__version__,
"title": title,
"time_stamp": format_local_datetime(datetime.datetime.now()),
"extra_css": self.extra_css,
"has_arcs": self.has_arcs,
"show_contexts": self.config.show_contexts,
"statics": {},
# Constants for all reports.
# These css classes determine which lines are highlighted by default.
"category": {
"exc": "exc show_exc",
"mis": "mis show_mis",
"par": "par run show_par",
"run": "run",
"exc2": "exc exc2 show_exc",
"mis2": "mis mis2 show_mis",
"par2": "par par2 ru2 show_par",
"run2": "run run2",
},
}
self.index_tmpl = Templite(read_data("index.html"), self.template_globals)
self.pyfile_html_source = read_data("pyfile.html")
self.source_tmpl = Templite(self.pyfile_html_source, self.template_globals)
def new_index_page(self, noun: str, plural_noun: str) -> IndexPage:
"""Create an IndexPage for a kind of region."""
return IndexPage(
noun=noun,
plural=plural_noun,
filename="index.html" if noun == "file" else f"{noun}_index.html",
summaries=[],
totals=Numbers(precision=self.config.precision),
skipped_covered_count=0,
skipped_empty_count=0,
)
def report(self, morfs: Iterable[TMorf] | None) -> float:
"""Generate an HTML report for `morfs`.
`morfs` is a list of modules or file names.
"""
# Read the status data and check that this run used the same
# global data as the last run.
self.incr.read()
self.incr.check_global_data(self.config, self.pyfile_html_source)
# Process all the files. For each page we need to supply a link
# to the next and previous page.
files_to_report = []
have_data = False
for fr, analysis in get_analysis_to_report(self.coverage, morfs):
have_data = True
ftr = FileToReport(fr, analysis)
if self.should_report(analysis, self.index_pages["file"]):
files_to_report.append(ftr)
else:
file_be_gone(os.path.join(self.directory, ftr.html_filename))
if not have_data:
raise NoDataError("No data to report.")
self.make_directory()
self.make_local_static_report_files()
if files_to_report:
for ftr1, ftr2 in zip(files_to_report[:-1], files_to_report[1:]):
ftr1.next_html = ftr2.html_filename
ftr2.prev_html = ftr1.html_filename
files_to_report[0].prev_html = "index.html"
files_to_report[-1].next_html = "index.html"
for ftr in files_to_report:
self.write_html_page(ftr)
for noun, plural_noun in ftr.fr.code_region_kinds():
if noun not in self.index_pages:
self.index_pages[noun] = self.new_index_page(noun, plural_noun)
# Write the index page.
if files_to_report:
first_html = files_to_report[0].html_filename
final_html = files_to_report[-1].html_filename
else:
first_html = final_html = "index.html"
self.write_file_index_page(first_html, final_html)
# Write function and class index pages.
self.write_region_index_pages(files_to_report)
return (
self.index_pages["file"].totals.n_statements
and self.index_pages["file"].totals.pc_covered
)
def make_directory(self) -> None:
"""Make sure our htmlcov directory exists."""
ensure_dir(self.directory)
if not os.listdir(self.directory):
self.directory_was_empty = True
def copy_static_file(self, src: str, slug: str = "") -> None:
"""Copy a static file into the output directory with cache busting."""
dest = copy_with_cache_bust(src, self.directory)
if not slug:
slug = os.path.basename(src).replace(".", "_")
self.template_globals["statics"][slug] = dest # type: ignore
def make_local_static_report_files(self) -> None:
"""Make local instances of static files for HTML report."""
# The files we provide must always be copied.
for static in self.STATIC_FILES:
self.copy_static_file(data_filename(static))
# The user may have extra CSS they want copied.
if self.extra_css:
assert self.config.extra_css is not None
self.copy_static_file(self.config.extra_css, slug="extra_css")
# Only write the .gitignore file if the directory was originally empty.
# .gitignore can't be copied from the source tree because if it was in
# the source tree, it would stop the static files from being checked in.
if self.directory_was_empty:
with open(os.path.join(self.directory, ".gitignore"), "w", encoding="utf-8") as fgi:
fgi.write("# Created by coverage.py\n*\n")
def should_report(self, analysis: Analysis, index_page: IndexPage) -> bool:
"""Determine if we'll report this file or region."""
# Get the numbers for this file.
nums = analysis.numbers
index_page.totals += nums
if self.skip_covered:
# Don't report on 100% files.
no_missing_lines = (nums.n_missing == 0) # fmt: skip
no_missing_branches = (nums.n_partial_branches == 0) # fmt: skip
if no_missing_lines and no_missing_branches:
index_page.skipped_covered_count += 1
return False
if self.skip_empty:
# Don't report on empty files.
if nums.n_statements == 0:
index_page.skipped_empty_count += 1
return False
return True
def write_html_page(self, ftr: FileToReport) -> None:
"""Generate an HTML page for one source file.
If the page on disk is already correct based on our incremental status
checking, then the page doesn't have to be generated, and this function
only does page summary bookkeeping.
"""
# Find out if the page on disk is already correct.
if self.incr.can_skip_file(self.data, ftr.fr, ftr.rootname):
self.index_pages["file"].summaries.append(self.incr.index_info(ftr.rootname))
return
# Write the HTML page for this source file.
file_data = self.datagen.data_for_file(ftr.fr, ftr.analysis)
contexts = collections.Counter(c for cline in file_data.lines for c in cline.contexts)
context_codes = {y: i for (i, y) in enumerate(x[0] for x in contexts.most_common())}
if context_codes:
contexts_json = json.dumps(
{encode_int(v): k for (k, v) in context_codes.items()},
indent=2,
)
else:
contexts_json = None
for ldata in file_data.lines:
# Build the HTML for the line.
html_parts = []
for tok_type, tok_text in ldata.tokens:
if tok_type == "ws":
html_parts.append(escape(tok_text))
else:
tok_html = escape(tok_text) or " "
html_parts.append(f'{tok_html}')
ldata.html = "".join(html_parts)
if ldata.context_list:
encoded_contexts = [
encode_int(context_codes[c_context]) for c_context in ldata.context_list
]
code_width = max(len(ec) for ec in encoded_contexts)
ldata.context_str = str(code_width) + "".join(
ec.ljust(code_width) for ec in encoded_contexts
)
else:
ldata.context_str = ""
if ldata.short_annotations:
# 202F is NARROW NO-BREAK SPACE.
# 219B is RIGHTWARDS ARROW WITH STROKE.
ldata.annotate = ", ".join(
f"{ldata.number} ↛ {d}" for d in ldata.short_annotations
)
else:
ldata.annotate = None
if ldata.long_annotations:
longs = ldata.long_annotations
# A line can only have two branch destinations. If there were
# two missing, we would have written one as "always raised."
assert len(longs) == 1, (
f"Had long annotations in {ftr.fr.relative_filename()}: {longs}"
)
ldata.annotate_long = longs[0]
else:
ldata.annotate_long = None
css_classes = []
if ldata.category:
css_classes.append(
self.template_globals["category"][ldata.category], # type: ignore[index]
)
ldata.css_class = " ".join(css_classes) or "pln"
html_path = os.path.join(self.directory, ftr.html_filename)
html = self.source_tmpl.render(
{
**file_data.__dict__,
"contexts_json": contexts_json,
"prev_html": ftr.prev_html,
"next_html": ftr.next_html,
}
)
write_html(html_path, html)
# Save this file's information for the index page.
index_info = IndexItem(
url=ftr.html_filename,
file=escape(ftr.fr.relative_filename()),
nums=ftr.analysis.numbers,
)
self.index_pages["file"].summaries.append(index_info)
self.incr.set_index_info(ftr.rootname, index_info)
def write_file_index_page(self, first_html: str, final_html: str) -> None:
"""Write the file index page for this report."""
index_file = self.write_index_page(
self.index_pages["file"],
first_html=first_html,
final_html=final_html,
)
print_href = stdout_link(index_file, f"file://{os.path.abspath(index_file)}")
self.coverage._message(f"Wrote HTML report to {print_href}")
# Write the latest hashes for next time.
self.incr.write()
def write_region_index_pages(self, files_to_report: Iterable[FileToReport]) -> None:
"""Write the other index pages for this report."""
for ftr in files_to_report:
region_nouns = [pair[0] for pair in ftr.fr.code_region_kinds()]
num_lines = len(ftr.fr.source().splitlines())
regions = ftr.fr.code_regions()
for noun in region_nouns:
page_data = self.index_pages[noun]
outside_lines = set(range(1, num_lines + 1))
for region in regions:
if region.kind != noun:
continue
outside_lines -= region.lines
narrower = AnalysisNarrower(ftr.analysis)
narrower.add_regions(r.lines for r in regions if r.kind == noun)
narrower.add_regions([outside_lines])
for region in regions:
if region.kind != noun:
continue
analysis = narrower.narrow(region.lines)
if not self.should_report(analysis, page_data):
continue
sorting_name = region.name.rpartition(".")[-1].lstrip("_")
page_data.summaries.append(
IndexItem(
url=f"{ftr.html_filename}#t{region.start}",
file=escape(ftr.fr.relative_filename()),
description=(
f""
+ escape(region.name)
+ ""
),
nums=analysis.numbers,
)
)
analysis = narrower.narrow(outside_lines)
if self.should_report(analysis, page_data):
page_data.summaries.append(
IndexItem(
url=ftr.html_filename,
file=escape(ftr.fr.relative_filename()),
description=(
""
+ f"(no {escape(noun)})"
+ ""
),
nums=analysis.numbers,
)
)
for noun, index_page in self.index_pages.items():
if noun != "file":
self.write_index_page(index_page)
def write_index_page(self, index_page: IndexPage, **kwargs: str) -> str:
"""Write an index page specified by `index_page`.
Returns the filename created.
"""
skipped_covered_msg = skipped_empty_msg = ""
if n := index_page.skipped_covered_count:
word = plural(n, index_page.noun, index_page.plural)
skipped_covered_msg = f"{n} {word} skipped due to complete coverage."
if n := index_page.skipped_empty_count:
word = plural(n, index_page.noun, index_page.plural)
skipped_empty_msg = f"{n} empty {word} skipped."
index_buttons = [
{
"label": ip.plural.title(),
"url": ip.filename if ip.noun != index_page.noun else "",
"current": ip.noun == index_page.noun,
}
for ip in self.index_pages.values()
]
render_data = {
"regions": index_page.summaries,
"totals": index_page.totals,
"noun": index_page.noun,
"region_noun": index_page.noun if index_page.noun != "file" else "",
"skip_covered": self.skip_covered,
"skipped_covered_msg": skipped_covered_msg,
"skipped_empty_msg": skipped_empty_msg,
"first_html": "",
"final_html": "",
"index_buttons": index_buttons,
}
render_data.update(kwargs)
html = self.index_tmpl.render(render_data)
index_file = os.path.join(self.directory, index_page.filename)
write_html(index_file, html)
return index_file
@dataclass
class FileInfo:
"""Summary of the information from last rendering, to avoid duplicate work."""
hash: str = ""
index: IndexItem = field(default_factory=IndexItem)
class IncrementalChecker:
"""Logic and data to support incremental reporting.
When generating an HTML report, often only a few of the source files have
changed since the last time we made the HTML report. This means previously
created HTML pages can be reused without generating them again, speeding
the command.
This class manages a JSON data file that captures enough information to
know whether an HTML page for a .py file needs to be regenerated or not.
The data file also needs to store all the information needed to create the
entry for the file on the index page so that if the HTML page is reused,
the index page can still be created to refer to it.
The data looks like::
{
"note": "This file is an internal implementation detail ...",
// A fixed number indicating the data format. STATUS_FORMAT
"format": 5,
// The version of coverage.py
"version": "7.4.4",
// A hash of a number of global things, including the configuration
// settings and the pyfile.html template itself.
"globals": "540ee119c15d52a68a53fe6f0897346d",
"files": {
// An entry for each source file keyed by the flat_rootname().
"z_7b071bdc2a35fa80___init___py": {
// Hash of the source, the text of the .py file.
"hash": "e45581a5b48f879f301c0f30bf77a50c",
// Information for the index.html file.
"index": {
"url": "z_7b071bdc2a35fa80___init___py.html",
"file": "cogapp/__init__.py",
"description": "",
// The Numbers for this file.
"nums": { "precision": 2, "n_files": 1, "n_statements": 43, ... }
}
},
...
}
}
"""
STATUS_FILE = "status.json"
STATUS_FORMAT = 5
NOTE = (
"This file is an internal implementation detail to speed up HTML report"
+ " generation. Its format can change at any time. You might be looking"
+ " for the JSON report: https://coverage.rtfd.io/cmd.html#cmd-json"
)
def __init__(self, directory: str) -> None:
self.directory = directory
self._reset()
def _reset(self) -> None:
"""Initialize to empty. Causes all files to be reported."""
self.globals = ""
self.files: dict[str, FileInfo] = {}
def read(self) -> None:
"""Read the information we stored last time."""
try:
status_file = os.path.join(self.directory, self.STATUS_FILE)
with open(status_file, encoding="utf-8") as fstatus:
status = json.load(fstatus)
except (OSError, ValueError):
# Status file is missing or malformed.
usable = False
else:
if status["format"] != self.STATUS_FORMAT:
usable = False
elif status["version"] != coverage.__version__:
usable = False
else:
usable = True
if usable:
self.files = {}
for filename, filedict in status["files"].items():
indexdict = filedict["index"]
index_item = IndexItem(**indexdict)
index_item.nums = Numbers(**indexdict["nums"])
fileinfo = FileInfo(
hash=filedict["hash"],
index=index_item,
)
self.files[filename] = fileinfo
self.globals = status["globals"]
else:
self._reset()
def write(self) -> None:
"""Write the current status."""
status_file = os.path.join(self.directory, self.STATUS_FILE)
status_data = {
"note": self.NOTE,
"format": self.STATUS_FORMAT,
"version": coverage.__version__,
"globals": self.globals,
"files": {fname: dataclasses.asdict(finfo) for fname, finfo in self.files.items()},
}
with open(status_file, "w", encoding="utf-8") as fout:
json.dump(status_data, fout, separators=(",", ":"))
def check_global_data(self, *data: Any) -> None:
"""Check the global data that can affect incremental reporting.
Pass in whatever global information could affect the content of the
HTML pages. If the global data has changed since last time, this will
clear the data so that all files are regenerated.
"""
m = Hasher()
for d in data:
m.update(d)
these_globals = m.hexdigest()
if self.globals != these_globals:
self._reset()
self.globals = these_globals
def can_skip_file(self, data: CoverageData, fr: FileReporter, rootname: str) -> bool:
"""Can we skip reporting this file?
`data` is a CoverageData object, `fr` is a `FileReporter`, and
`rootname` is the name being used for the file.
Returns True if the HTML page is fine as-is, False if we need to recreate
the HTML page.
"""
m = Hasher()
m.update(fr.source().encode("utf-8"))
add_data_to_hash(data, fr.filename, m)
this_hash = m.hexdigest()
file_info = self.files.setdefault(rootname, FileInfo())
if this_hash == file_info.hash:
# Nothing has changed to require the file to be reported again.
return True
else:
# File has changed, record the latest hash and force regeneration.
file_info.hash = this_hash
return False
def index_info(self, fname: str) -> IndexItem:
"""Get the information for index.html for `fname`."""
return self.files.get(fname, FileInfo()).index
def set_index_info(self, fname: str, info: IndexItem) -> None:
"""Set the information for index.html for `fname`."""
self.files.setdefault(fname, FileInfo()).index = info
# Helpers for templates and generating HTML
def escape(t: str) -> str:
"""HTML-escape the text in `t`.
This is only suitable for HTML text, not attributes.
"""
# Convert HTML special chars into HTML entities.
return t.replace("&", "&").replace("<", "<")
def pair(ratio: tuple[int, int]) -> str:
"""Format a pair of numbers so JavaScript can read them in an attribute."""
return "{} {}".format(*ratio)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9431894
coverage-7.11.0/coverage/htmlfiles/ 0000755 0001751 0001751 00000000000 15073731560 016632 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/htmlfiles/coverage_html.js 0000644 0001751 0001751 00000061602 15073731535 022016 0 ustar 00runner runner // Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
// For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
// Coverage.py HTML report browser code.
/*jslint browser: true, sloppy: true, vars: true, plusplus: true, maxerr: 50, indent: 4 */
/*global coverage: true, document, window, $ */
coverage = {};
// General helpers
function debounce(callback, wait) {
let timeoutId = null;
return function(...args) {
clearTimeout(timeoutId);
timeoutId = setTimeout(() => {
callback.apply(this, args);
}, wait);
};
};
function checkVisible(element) {
const rect = element.getBoundingClientRect();
const viewBottom = Math.max(document.documentElement.clientHeight, window.innerHeight);
const viewTop = 30;
return !(rect.bottom < viewTop || rect.top >= viewBottom);
}
function on_click(sel, fn) {
const elt = document.querySelector(sel);
if (elt) {
elt.addEventListener("click", fn);
}
}
// Helpers for table sorting
function getCellValue(row, column = 0) {
const cell = row.cells[column] // nosemgrep: eslint.detect-object-injection
if (cell.childElementCount == 1) {
var child = cell.firstElementChild;
if (child.tagName === "A") {
child = child.firstElementChild;
}
if (child instanceof HTMLDataElement && child.value) {
return child.value;
}
}
return cell.innerText || cell.textContent;
}
function rowComparator(rowA, rowB, column = 0) {
let valueA = getCellValue(rowA, column);
let valueB = getCellValue(rowB, column);
if (!isNaN(valueA) && !isNaN(valueB)) {
return valueA - valueB;
}
return valueA.localeCompare(valueB, undefined, {numeric: true});
}
function sortColumn(th) {
// Get the current sorting direction of the selected header,
// clear state on other headers and then set the new sorting direction.
const currentSortOrder = th.getAttribute("aria-sort");
[...th.parentElement.cells].forEach(header => header.setAttribute("aria-sort", "none"));
var direction;
if (currentSortOrder === "none") {
direction = th.dataset.defaultSortOrder || "ascending";
}
else if (currentSortOrder === "ascending") {
direction = "descending";
}
else {
direction = "ascending";
}
th.setAttribute("aria-sort", direction);
const column = [...th.parentElement.cells].indexOf(th)
// Sort all rows and afterwards append them in order to move them in the DOM.
Array.from(th.closest("table").querySelectorAll("tbody tr"))
.sort((rowA, rowB) => rowComparator(rowA, rowB, column) * (direction === "ascending" ? 1 : -1))
.forEach(tr => tr.parentElement.appendChild(tr));
// Save the sort order for next time.
if (th.id !== "region") {
let th_id = "file"; // Sort by file if we don't have a column id
let current_direction = direction;
const stored_list = localStorage.getItem(coverage.INDEX_SORT_STORAGE);
if (stored_list) {
({th_id, direction} = JSON.parse(stored_list))
}
localStorage.setItem(coverage.INDEX_SORT_STORAGE, JSON.stringify({
"th_id": th.id,
"direction": current_direction
}));
if (th.id !== th_id || document.getElementById("region")) {
// Sort column has changed, unset sorting by function or class.
localStorage.setItem(coverage.SORTED_BY_REGION, JSON.stringify({
"by_region": false,
"region_direction": current_direction
}));
}
}
else {
// Sort column has changed to by function or class, remember that.
localStorage.setItem(coverage.SORTED_BY_REGION, JSON.stringify({
"by_region": true,
"region_direction": direction
}));
}
}
// Find all the elements with data-shortcut attribute, and use them to assign a shortcut key.
coverage.assign_shortkeys = function () {
document.querySelectorAll("[data-shortcut]").forEach(element => {
document.addEventListener("keypress", event => {
if (event.target.tagName.toLowerCase() === "input") {
return; // ignore keypress from search filter
}
if (event.key === element.dataset.shortcut) {
element.click();
}
});
});
};
// Create the events for the filter box.
coverage.wire_up_filter = function () {
// Populate the filter and hide100 inputs if there are saved values for them.
const saved_filter_value = localStorage.getItem(coverage.FILTER_STORAGE);
if (saved_filter_value) {
document.getElementById("filter").value = saved_filter_value;
}
const saved_hide100_value = localStorage.getItem(coverage.HIDE100_STORAGE);
if (saved_hide100_value) {
document.getElementById("hide100").checked = JSON.parse(saved_hide100_value);
}
// Cache elements.
const table = document.querySelector("table.index");
const table_body_rows = table.querySelectorAll("tbody tr");
const no_rows = document.getElementById("no_rows");
// Observe filter keyevents.
const filter_handler = (event => {
// Keep running total of each metric, first index contains number of shown rows
const totals = new Array(table.rows[0].cells.length).fill(0);
// Accumulate the percentage as fraction
totals[totals.length - 1] = { "numer": 0, "denom": 0 }; // nosemgrep: eslint.detect-object-injection
var text = document.getElementById("filter").value;
// Store filter value
localStorage.setItem(coverage.FILTER_STORAGE, text);
const casefold = (text === text.toLowerCase());
const hide100 = document.getElementById("hide100").checked;
// Store hide value.
localStorage.setItem(coverage.HIDE100_STORAGE, JSON.stringify(hide100));
// Hide / show elements.
table_body_rows.forEach(row => {
var show = false;
// Check the text filter.
for (let column = 0; column < totals.length; column++) {
cell = row.cells[column];
if (cell.classList.contains("name")) {
var celltext = cell.textContent;
if (casefold) {
celltext = celltext.toLowerCase();
}
if (celltext.includes(text)) {
show = true;
}
}
}
// Check the "hide covered" filter.
if (show && hide100) {
const [numer, denom] = row.cells[row.cells.length - 1].dataset.ratio.split(" ");
show = (numer !== denom);
}
if (!show) {
// hide
row.classList.add("hidden");
return;
}
// show
row.classList.remove("hidden");
totals[0]++;
for (let column = 0; column < totals.length; column++) {
// Accumulate dynamic totals
cell = row.cells[column] // nosemgrep: eslint.detect-object-injection
if (cell.classList.contains("name")) {
continue;
}
if (column === totals.length - 1) {
// Last column contains percentage
const [numer, denom] = cell.dataset.ratio.split(" ");
totals[column]["numer"] += parseInt(numer, 10); // nosemgrep: eslint.detect-object-injection
totals[column]["denom"] += parseInt(denom, 10); // nosemgrep: eslint.detect-object-injection
}
else {
totals[column] += parseInt(cell.textContent, 10); // nosemgrep: eslint.detect-object-injection
}
}
});
// Show placeholder if no rows will be displayed.
if (!totals[0]) {
// Show placeholder, hide table.
no_rows.style.display = "block";
table.style.display = "none";
return;
}
// Hide placeholder, show table.
no_rows.style.display = null;
table.style.display = null;
const footer = table.tFoot.rows[0];
// Calculate new dynamic sum values based on visible rows.
for (let column = 0; column < totals.length; column++) {
// Get footer cell element.
const cell = footer.cells[column]; // nosemgrep: eslint.detect-object-injection
if (cell.classList.contains("name")) {
continue;
}
// Set value into dynamic footer cell element.
if (column === totals.length - 1) {
// Percentage column uses the numerator and denominator,
// and adapts to the number of decimal places.
const match = /\.([0-9]+)/.exec(cell.textContent);
const places = match ? match[1].length : 0;
const { numer, denom } = totals[column]; // nosemgrep: eslint.detect-object-injection
cell.dataset.ratio = `${numer} ${denom}`;
// Check denom to prevent NaN if filtered files contain no statements
cell.textContent = denom
? `${(numer * 100 / denom).toFixed(places)}%`
: `${(100).toFixed(places)}%`;
}
else {
cell.textContent = totals[column]; // nosemgrep: eslint.detect-object-injection
}
}
});
document.getElementById("filter").addEventListener("input", debounce(filter_handler));
document.getElementById("hide100").addEventListener("input", debounce(filter_handler));
// Trigger change event on setup, to force filter on page refresh
// (filter value may still be present).
document.getElementById("filter").dispatchEvent(new Event("input"));
document.getElementById("hide100").dispatchEvent(new Event("input"));
};
coverage.FILTER_STORAGE = "COVERAGE_FILTER_VALUE";
coverage.HIDE100_STORAGE = "COVERAGE_HIDE100_VALUE";
// Set up the click-to-sort columns.
coverage.wire_up_sorting = function () {
document.querySelectorAll("[data-sortable] th[aria-sort]").forEach(
th => th.addEventListener("click", e => sortColumn(e.target))
);
// Look for a localStorage item containing previous sort settings:
let th_id = "file", direction = "ascending";
const stored_list = localStorage.getItem(coverage.INDEX_SORT_STORAGE);
if (stored_list) {
({th_id, direction} = JSON.parse(stored_list));
}
let by_region = false, region_direction = "ascending";
const sorted_by_region = localStorage.getItem(coverage.SORTED_BY_REGION);
if (sorted_by_region) {
({
by_region,
region_direction
} = JSON.parse(sorted_by_region));
}
const region_id = "region";
if (by_region && document.getElementById(region_id)) {
direction = region_direction;
}
// If we are in a page that has a column with id of "region", sort on
// it if the last sort was by function or class.
let th;
if (document.getElementById(region_id)) {
th = document.getElementById(by_region ? region_id : th_id);
}
else {
th = document.getElementById(th_id);
}
th.setAttribute("aria-sort", direction === "ascending" ? "descending" : "ascending");
th.click()
};
coverage.INDEX_SORT_STORAGE = "COVERAGE_INDEX_SORT_2";
coverage.SORTED_BY_REGION = "COVERAGE_SORT_REGION";
// Loaded on index.html
coverage.index_ready = function () {
coverage.assign_shortkeys();
coverage.wire_up_filter();
coverage.wire_up_sorting();
on_click(".button_prev_file", coverage.to_prev_file);
on_click(".button_next_file", coverage.to_next_file);
on_click(".button_show_hide_help", coverage.show_hide_help);
};
// -- pyfile stuff --
coverage.LINE_FILTERS_STORAGE = "COVERAGE_LINE_FILTERS";
coverage.pyfile_ready = function () {
// If we're directed to a particular line number, highlight the line.
var frag = location.hash;
if (frag.length > 2 && frag[1] === "t") {
document.querySelector(frag).closest(".n").classList.add("highlight");
coverage.set_sel(parseInt(frag.substr(2), 10));
}
else {
coverage.set_sel(0);
}
on_click(".button_toggle_run", coverage.toggle_lines);
on_click(".button_toggle_mis", coverage.toggle_lines);
on_click(".button_toggle_exc", coverage.toggle_lines);
on_click(".button_toggle_par", coverage.toggle_lines);
on_click(".button_next_chunk", coverage.to_next_chunk_nicely);
on_click(".button_prev_chunk", coverage.to_prev_chunk_nicely);
on_click(".button_top_of_page", coverage.to_top);
on_click(".button_first_chunk", coverage.to_first_chunk);
on_click(".button_prev_file", coverage.to_prev_file);
on_click(".button_next_file", coverage.to_next_file);
on_click(".button_to_index", coverage.to_index);
on_click(".button_show_hide_help", coverage.show_hide_help);
coverage.filters = undefined;
try {
coverage.filters = localStorage.getItem(coverage.LINE_FILTERS_STORAGE);
} catch(err) {}
if (coverage.filters) {
coverage.filters = JSON.parse(coverage.filters);
}
else {
coverage.filters = {run: false, exc: true, mis: true, par: true};
}
for (cls in coverage.filters) {
coverage.set_line_visibilty(cls, coverage.filters[cls]); // nosemgrep: eslint.detect-object-injection
}
coverage.assign_shortkeys();
coverage.init_scroll_markers();
coverage.wire_up_sticky_header();
document.querySelectorAll("[id^=ctxs]").forEach(
cbox => cbox.addEventListener("click", coverage.expand_contexts)
);
// Rebuild scroll markers when the window height changes.
window.addEventListener("resize", coverage.build_scroll_markers);
};
coverage.toggle_lines = function (event) {
const btn = event.target.closest("button");
const category = btn.value
const show = !btn.classList.contains("show_" + category);
coverage.set_line_visibilty(category, show);
coverage.build_scroll_markers();
coverage.filters[category] = show;
try {
localStorage.setItem(coverage.LINE_FILTERS_STORAGE, JSON.stringify(coverage.filters));
} catch(err) {}
};
coverage.set_line_visibilty = function (category, should_show) {
const cls = "show_" + category;
const btn = document.querySelector(".button_toggle_" + category);
if (btn) {
if (should_show) {
document.querySelectorAll("#source ." + category).forEach(e => e.classList.add(cls));
btn.classList.add(cls);
}
else {
document.querySelectorAll("#source ." + category).forEach(e => e.classList.remove(cls));
btn.classList.remove(cls);
}
}
};
// Return the nth line div.
coverage.line_elt = function (n) {
return document.getElementById("t" + n)?.closest("p");
};
// Set the selection. b and e are line numbers.
coverage.set_sel = function (b, e) {
// The first line selected.
coverage.sel_begin = b;
// The next line not selected.
coverage.sel_end = (e === undefined) ? b+1 : e;
};
coverage.to_top = function () {
coverage.set_sel(0, 1);
coverage.scroll_window(0);
};
coverage.to_first_chunk = function () {
coverage.set_sel(0, 1);
coverage.to_next_chunk();
};
coverage.to_prev_file = function () {
window.location = document.getElementById("prevFileLink").href;
}
coverage.to_next_file = function () {
window.location = document.getElementById("nextFileLink").href;
}
coverage.to_index = function () {
location.href = document.getElementById("indexLink").href;
}
coverage.show_hide_help = function () {
const helpCheck = document.getElementById("help_panel_state")
helpCheck.checked = !helpCheck.checked;
}
// Return a string indicating what kind of chunk this line belongs to,
// or null if not a chunk.
coverage.chunk_indicator = function (line_elt) {
const classes = line_elt?.className;
if (!classes) {
return null;
}
const match = classes.match(/\bshow_\w+\b/);
if (!match) {
return null;
}
return match[0];
};
coverage.to_next_chunk = function () {
const c = coverage;
// Find the start of the next colored chunk.
var probe = c.sel_end;
var chunk_indicator, probe_line;
while (true) {
probe_line = c.line_elt(probe);
if (!probe_line) {
return;
}
chunk_indicator = c.chunk_indicator(probe_line);
if (chunk_indicator) {
break;
}
probe++;
}
// There's a next chunk, `probe` points to it.
var begin = probe;
// Find the end of this chunk.
var next_indicator = chunk_indicator;
while (next_indicator === chunk_indicator) {
probe++;
probe_line = c.line_elt(probe);
next_indicator = c.chunk_indicator(probe_line);
}
c.set_sel(begin, probe);
c.show_selection();
};
coverage.to_prev_chunk = function () {
const c = coverage;
// Find the end of the prev colored chunk.
var probe = c.sel_begin-1;
var probe_line = c.line_elt(probe);
if (!probe_line) {
return;
}
var chunk_indicator = c.chunk_indicator(probe_line);
while (probe > 1 && !chunk_indicator) {
probe--;
probe_line = c.line_elt(probe);
if (!probe_line) {
return;
}
chunk_indicator = c.chunk_indicator(probe_line);
}
// There's a prev chunk, `probe` points to its last line.
var end = probe+1;
// Find the beginning of this chunk.
var prev_indicator = chunk_indicator;
while (prev_indicator === chunk_indicator) {
probe--;
if (probe <= 0) {
return;
}
probe_line = c.line_elt(probe);
prev_indicator = c.chunk_indicator(probe_line);
}
c.set_sel(probe+1, end);
c.show_selection();
};
// Returns 0, 1, or 2: how many of the two ends of the selection are on
// the screen right now?
coverage.selection_ends_on_screen = function () {
if (coverage.sel_begin === 0) {
return 0;
}
const begin = coverage.line_elt(coverage.sel_begin);
const end = coverage.line_elt(coverage.sel_end-1);
return (
(checkVisible(begin) ? 1 : 0)
+ (checkVisible(end) ? 1 : 0)
);
};
coverage.to_next_chunk_nicely = function () {
if (coverage.selection_ends_on_screen() === 0) {
// The selection is entirely off the screen:
// Set the top line on the screen as selection.
// This will select the top-left of the viewport
// As this is most likely the span with the line number we take the parent
const line = document.elementFromPoint(0, 0).parentElement;
if (line.parentElement !== document.getElementById("source")) {
// The element is not a source line but the header or similar
coverage.select_line_or_chunk(1);
}
else {
// We extract the line number from the id
coverage.select_line_or_chunk(parseInt(line.id.substring(1), 10));
}
}
coverage.to_next_chunk();
};
coverage.to_prev_chunk_nicely = function () {
if (coverage.selection_ends_on_screen() === 0) {
// The selection is entirely off the screen:
// Set the lowest line on the screen as selection.
// This will select the bottom-left of the viewport
// As this is most likely the span with the line number we take the parent
const line = document.elementFromPoint(document.documentElement.clientHeight-1, 0).parentElement;
if (line.parentElement !== document.getElementById("source")) {
// The element is not a source line but the header or similar
coverage.select_line_or_chunk(coverage.lines_len);
}
else {
// We extract the line number from the id
coverage.select_line_or_chunk(parseInt(line.id.substring(1), 10));
}
}
coverage.to_prev_chunk();
};
// Select line number lineno, or if it is in a colored chunk, select the
// entire chunk
coverage.select_line_or_chunk = function (lineno) {
var c = coverage;
var probe_line = c.line_elt(lineno);
if (!probe_line) {
return;
}
var the_indicator = c.chunk_indicator(probe_line);
if (the_indicator) {
// The line is in a highlighted chunk.
// Search backward for the first line.
var probe = lineno;
var indicator = the_indicator;
while (probe > 0 && indicator === the_indicator) {
probe--;
probe_line = c.line_elt(probe);
if (!probe_line) {
break;
}
indicator = c.chunk_indicator(probe_line);
}
var begin = probe + 1;
// Search forward for the last line.
probe = lineno;
indicator = the_indicator;
while (indicator === the_indicator) {
probe++;
probe_line = c.line_elt(probe);
indicator = c.chunk_indicator(probe_line);
}
coverage.set_sel(begin, probe);
}
else {
coverage.set_sel(lineno);
}
};
coverage.show_selection = function () {
// Highlight the lines in the chunk
document.querySelectorAll("#source .highlight").forEach(e => e.classList.remove("highlight"));
for (let probe = coverage.sel_begin; probe < coverage.sel_end; probe++) {
coverage.line_elt(probe).querySelector(".n").classList.add("highlight");
}
coverage.scroll_to_selection();
};
coverage.scroll_to_selection = function () {
// Scroll the page if the chunk isn't fully visible.
if (coverage.selection_ends_on_screen() < 2) {
const element = coverage.line_elt(coverage.sel_begin);
coverage.scroll_window(element.offsetTop - 60);
}
};
coverage.scroll_window = function (to_pos) {
window.scroll({top: to_pos, behavior: "smooth"});
};
coverage.init_scroll_markers = function () {
// Init some variables
coverage.lines_len = document.querySelectorAll("#source > p").length;
// Build html
coverage.build_scroll_markers();
};
coverage.build_scroll_markers = function () {
const temp_scroll_marker = document.getElementById("scroll_marker")
if (temp_scroll_marker) temp_scroll_marker.remove();
// Don't build markers if the window has no scroll bar.
if (document.body.scrollHeight <= window.innerHeight) {
return;
}
const marker_scale = window.innerHeight / document.body.scrollHeight;
const line_height = Math.min(Math.max(3, window.innerHeight / coverage.lines_len), 10);
let previous_line = -99, last_mark, last_top;
const scroll_marker = document.createElement("div");
scroll_marker.id = "scroll_marker";
document.getElementById("source").querySelectorAll(
"p.show_run, p.show_mis, p.show_exc, p.show_exc, p.show_par"
).forEach(element => {
const line_top = Math.floor(element.offsetTop * marker_scale);
const line_number = parseInt(element.querySelector(".n a").id.substr(1));
if (line_number === previous_line + 1) {
// If this solid missed block just make previous mark higher.
last_mark.style.height = `${line_top + line_height - last_top}px`;
}
else {
// Add colored line in scroll_marker block.
last_mark = document.createElement("div");
last_mark.id = `m${line_number}`;
last_mark.classList.add("marker");
last_mark.style.height = `${line_height}px`;
last_mark.style.top = `${line_top}px`;
scroll_marker.append(last_mark);
last_top = line_top;
}
previous_line = line_number;
});
// Append last to prevent layout calculation
document.body.append(scroll_marker);
};
coverage.wire_up_sticky_header = function () {
const header = document.querySelector("header");
const header_bottom = (
header.querySelector(".content h2").getBoundingClientRect().top -
header.getBoundingClientRect().top
);
function updateHeader() {
if (window.scrollY > header_bottom) {
header.classList.add("sticky");
}
else {
header.classList.remove("sticky");
}
}
window.addEventListener("scroll", updateHeader);
updateHeader();
};
coverage.expand_contexts = function (e) {
var ctxs = e.target.parentNode.querySelector(".ctxs");
if (!ctxs.classList.contains("expanded")) {
var ctxs_text = ctxs.textContent;
var width = Number(ctxs_text[0]);
ctxs.textContent = "";
for (var i = 1; i < ctxs_text.length; i += width) {
key = ctxs_text.substring(i, i + width).trim();
ctxs.appendChild(document.createTextNode(contexts[key]));
ctxs.appendChild(document.createElement("br"));
}
ctxs.classList.add("expanded");
}
};
document.addEventListener("DOMContentLoaded", () => {
if (document.body.classList.contains("indexfile")) {
coverage.index_ready();
}
else {
coverage.pyfile_ready();
}
});
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/htmlfiles/favicon_32.png 0000644 0001751 0001751 00000003304 15073731535 021273 0 ustar 00runner runner PNG
IHDR Dคฦ PLTE 250SRS;A6
___^^_CJ>OXH# cm[fef05,[[\HPCFL?JIK<:< tjep\[gT_iX7 V_N]\](<;=&#$ ็ิ๊ึเXใYXซพแX๛๛๛ํืไัQฒพัญีํฤ๗๗๗๊๋๋๔สฯๆฟSฃท โY
แW๙๘๘็ๆๆ฿๗ฬุ๐ฦฤฤฤฤฺตฆธขดฒฌข฿Z๛YVJ;zG:vD7rC5\5*๕๓๓โ๚ฯา๊ยหโปMฌดศฅฐคฺUฺUฏษGO?l>0X2'ืืืฮฮฮษ฿ธฟิฐชฌฌปฯซMฉทหงขคฆฒลขGD@>v<7jw v{}f&Xึ๓UัQฬP[cPรMมK<4q:L+"๐๐๑฿฿฿ัััVฉผWงบขชฌคฉฉฌฆIกญภชฝv ณฉfz|3Wญภถทนฒทนฃฃงฐ TEญEaคAKPHz}ry{Lqzjvyxxกv u^jo3miqhmyc/Wbc`i{`P[*[ิ๘Zฒ๓Y๏Y๎YfๆY+แXฺ๘WSW{SีRCกRewRueRฮQPPQ+ะPวโO!ฌN N
หMI LพูK{KญฮJ\[JjYH ฒGจภEซE7E/ฑCRBfRBr@|ฐ>IDAT8หb&nNC%Nn& ฬ.ร๋ ccใ9นฝ]฿M ฏ)์อ/!ศ,ฏย\เi
6ณณขณ"#ณ๒ย๒]piงูแYQแู|ยp๒Pูค)S๎ส
Tมตช?'i๗{7๛๒S?ฟฌ
VT+* K;์/ฒฒฒJจ(/J(ซ T!ศ๒ @R`๗yํๅfeีSVnoฟ๓Xรํ:@Kุ}ม๒G+ฺ&$ุWี5งYป7mชyตึ[ไ ๙n{ทm็=,-,,,oด๚คผ็ใbเไฐฑ(฿c๏V๕ ฬายคbษR sWM\sฺทU-ถดถkด ณถpoM5ทuเgPp*(ฉ\Wดฝ/ฉฒฮ2=:lีๅ-i
mฎๆฌ ,1@ ฮLุ็e3sๅฝทึiหVYพ๚wรสIถ>b ข6ฆฆพ{vm น$๘วผึ๎๎i--ึญAfม 8'อี ๖๊Y+๎N8าาruฒร๓5 ,๋ซซKภaนตู๚๒๙o ,A*ฌำ$ฮจc0pv k฿ CC2nฝYb
ิฟ`ีย)ฌ oAGา ึ๓็ึ/rMผuๅงึถ๑วMไTGฮฆ-=ๆ ผjk๎ํไ๏g7ญึA[ฯษินGJ๊ใ >$;ฺฺิงJs10ฑ๙vNwฐ3s)>๒ะำใcอออ๓ gคฐฉ300ฒL77333w9,ไ๊"W[ป< A๑ `ชญ;^ซrฤ0sq
8Yใ`ศฮIr๙ๆS3^Bf>.~ฬชDษ({๚=ฮ ์ผ ๓eแษ^bน8R๏bW?YDฦ`dNษฤ%๛hRฟ@f ~PาNต5ทณs๖w4๗(ษฑ ทูt โผํ\Jk5XูกUผฉI\ZK . /๒%;่
IENDฎB` ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/htmlfiles/index.html 0000644 0001751 0001751 00000015271 15073731535 020637 0 ustar 00runner runner {# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 #}
{# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt #}
{{ title|escape }}
{% if extra_css %}
{% endif %}
{{ title|escape }}:
{{totals.pc_covered_str}}%
{% for ibtn in index_buttons %}
{{ ibtn.label }}{#-#}
{% endfor %}
{{line.number}}{{line.html}}
{% if line.context_list %}
{% endif %}
{# Things that should float right in the line. #}
{% if line.annotate %}
{{line.annotate}}{{line.annotate_long}}
{% endif %}
{% if line.contexts %}
{% endif %}
{# Things that should appear below the line. #}
{% if line.context_str %}
{{ line.context_str }}
{% endif %}
{% endjoined %}
{% endfor %}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/htmlfiles/style.css 0000644 0001751 0001751 00000036433 15073731535 020517 0 ustar 00runner runner @charset "UTF-8";
/* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
/* Don't edit this .css file. Edit the .scss file instead! */
html, body, h1, h2, h3, p, table, td, th { margin: 0; padding: 0; border: 0; font-weight: inherit; font-style: inherit; font-size: 100%; font-family: inherit; vertical-align: baseline; }
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Ubuntu, Cantarell, "Helvetica Neue", sans-serif; font-size: 1em; background: #fff; color: #000; }
@media (prefers-color-scheme: dark) { body { background: #1e1e1e; } }
@media (prefers-color-scheme: dark) { body { color: #eee; } }
html > body { font-size: 16px; }
a:active, a:focus { outline: 2px dashed #007acc; }
p { font-size: .875em; line-height: 1.4em; }
table { border-collapse: collapse; }
td { vertical-align: top; }
table tr.hidden { display: none !important; }
p#no_rows { display: none; font-size: 1.15em; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Ubuntu, Cantarell, "Helvetica Neue", sans-serif; }
a.nav { text-decoration: none; color: inherit; }
a.nav:hover { text-decoration: underline; color: inherit; }
.hidden { display: none; }
header { background: #f8f8f8; width: 100%; z-index: 2; border-bottom: 1px solid #ccc; }
@media (prefers-color-scheme: dark) { header { background: black; } }
@media (prefers-color-scheme: dark) { header { border-color: #333; } }
header .content { padding: 1rem 3.5rem; }
header h2 { margin-top: .5em; font-size: 1em; }
header h2 a.button { font-family: inherit; font-size: inherit; border: 1px solid; border-radius: .2em; background: #eee; color: inherit; text-decoration: none; padding: .1em .5em; margin: 1px calc(.1em + 1px); cursor: pointer; border-color: #ccc; }
@media (prefers-color-scheme: dark) { header h2 a.button { background: #333; } }
@media (prefers-color-scheme: dark) { header h2 a.button { border-color: #444; } }
header h2 a.button.current { border: 2px solid; background: #fff; border-color: #999; cursor: default; }
@media (prefers-color-scheme: dark) { header h2 a.button.current { background: #1e1e1e; } }
@media (prefers-color-scheme: dark) { header h2 a.button.current { border-color: #777; } }
header p.text { margin: .5em 0 -.5em; color: #666; font-style: italic; }
@media (prefers-color-scheme: dark) { header p.text { color: #aaa; } }
header.sticky { position: fixed; left: 0; right: 0; height: 2.5em; }
header.sticky .text { display: none; }
header.sticky h1, header.sticky h2 { font-size: 1em; margin-top: 0; display: inline-block; }
header.sticky .content { padding: 0.5rem 3.5rem; }
header.sticky .content p { font-size: 1em; }
header.sticky ~ #source { padding-top: 6.5em; }
main { position: relative; z-index: 1; }
footer { margin: 1rem 3.5rem; }
footer .content { padding: 0; color: #666; font-style: italic; }
@media (prefers-color-scheme: dark) { footer .content { color: #aaa; } }
#index { margin: 1rem 0 0 3.5rem; }
h1 { font-size: 1.25em; display: inline-block; }
#filter_container { float: right; margin: 0 2em 0 0; line-height: 1.66em; }
#filter_container #filter { width: 10em; padding: 0.2em 0.5em; border: 2px solid #ccc; background: #fff; color: #000; }
@media (prefers-color-scheme: dark) { #filter_container #filter { border-color: #444; } }
@media (prefers-color-scheme: dark) { #filter_container #filter { background: #1e1e1e; } }
@media (prefers-color-scheme: dark) { #filter_container #filter { color: #eee; } }
#filter_container #filter:focus { border-color: #007acc; }
#filter_container :disabled ~ label { color: #ccc; }
@media (prefers-color-scheme: dark) { #filter_container :disabled ~ label { color: #444; } }
#filter_container label { font-size: .875em; color: #666; }
@media (prefers-color-scheme: dark) { #filter_container label { color: #aaa; } }
header button { font-family: inherit; font-size: inherit; border: 1px solid; border-radius: .2em; background: #eee; color: inherit; text-decoration: none; padding: .1em .5em; margin: 1px calc(.1em + 1px); cursor: pointer; border-color: #ccc; }
@media (prefers-color-scheme: dark) { header button { background: #333; } }
@media (prefers-color-scheme: dark) { header button { border-color: #444; } }
header button:active, header button:focus { outline: 2px dashed #007acc; }
header button.run { background: #eeffee; }
@media (prefers-color-scheme: dark) { header button.run { background: #373d29; } }
header button.run.show_run { background: #dfd; border: 2px solid #00dd00; margin: 0 .1em; }
@media (prefers-color-scheme: dark) { header button.run.show_run { background: #373d29; } }
header button.mis { background: #ffeeee; }
@media (prefers-color-scheme: dark) { header button.mis { background: #4b1818; } }
header button.mis.show_mis { background: #fdd; border: 2px solid #ff0000; margin: 0 .1em; }
@media (prefers-color-scheme: dark) { header button.mis.show_mis { background: #4b1818; } }
header button.exc { background: #f7f7f7; }
@media (prefers-color-scheme: dark) { header button.exc { background: #333; } }
header button.exc.show_exc { background: #eee; border: 2px solid #808080; margin: 0 .1em; }
@media (prefers-color-scheme: dark) { header button.exc.show_exc { background: #333; } }
header button.par { background: #ffffd5; }
@media (prefers-color-scheme: dark) { header button.par { background: #650; } }
header button.par.show_par { background: #ffa; border: 2px solid #bbbb00; margin: 0 .1em; }
@media (prefers-color-scheme: dark) { header button.par.show_par { background: #650; } }
#help_panel, #source p .annotate.long { display: none; position: absolute; z-index: 999; background: #ffffcc; border: 1px solid #888; border-radius: .2em; color: #333; padding: .25em .5em; }
#source p .annotate.long { white-space: normal; float: right; top: 1.75em; right: 1em; height: auto; }
#help_panel_wrapper { float: right; position: relative; }
#keyboard_icon { margin: 5px; }
#help_panel_state { display: none; }
#help_panel { top: 25px; right: 0; padding: .75em; border: 1px solid #883; color: #333; }
#help_panel .keyhelp p { margin-top: .75em; }
#help_panel .legend { font-style: italic; margin-bottom: 1em; }
.indexfile #help_panel { width: 25em; }
.pyfile #help_panel { width: 18em; }
#help_panel_state:checked ~ #help_panel { display: block; }
kbd { border: 1px solid black; border-color: #888 #333 #333 #888; padding: .1em .35em; font-family: SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-weight: bold; background: #eee; border-radius: 3px; }
#source { padding: 1em 0 1em 3.5rem; font-family: SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
#source p { position: relative; white-space: pre; }
#source p * { box-sizing: border-box; }
#source p .n { float: left; text-align: right; width: 3.5rem; box-sizing: border-box; margin-left: -3.5rem; padding-right: 1em; color: #999; user-select: none; }
@media (prefers-color-scheme: dark) { #source p .n { color: #777; } }
#source p .n.highlight { background: #ffdd00; }
#source p .n a { scroll-margin-top: 6em; text-decoration: none; color: #999; }
@media (prefers-color-scheme: dark) { #source p .n a { color: #777; } }
#source p .n a:hover { text-decoration: underline; color: #999; }
@media (prefers-color-scheme: dark) { #source p .n a:hover { color: #777; } }
#source p .t { display: inline-block; width: 100%; box-sizing: border-box; margin-left: -.5em; padding-left: 0.3em; border-left: 0.2em solid #fff; }
@media (prefers-color-scheme: dark) { #source p .t { border-color: #1e1e1e; } }
#source p .t:hover { background: #f2f2f2; }
@media (prefers-color-scheme: dark) { #source p .t:hover { background: #282828; } }
#source p .t:hover ~ .r .annotate.long { display: block; }
#source p .t .com { color: #008000; font-style: italic; line-height: 1px; }
@media (prefers-color-scheme: dark) { #source p .t .com { color: #6a9955; } }
#source p .t .key { font-weight: bold; line-height: 1px; }
#source p .t .str, #source p .t .fst { color: #0451a5; }
@media (prefers-color-scheme: dark) { #source p .t .str, #source p .t .fst { color: #9cdcfe; } }
#source p.mis .t { border-left: 0.2em solid #ff0000; }
#source p.mis.show_mis .t { background: #fdd; }
@media (prefers-color-scheme: dark) { #source p.mis.show_mis .t { background: #4b1818; } }
#source p.mis.show_mis .t:hover { background: #f2d2d2; }
@media (prefers-color-scheme: dark) { #source p.mis.show_mis .t:hover { background: #532323; } }
#source p.mis.mis2 .t { border-left: 0.2em dotted #ff0000; }
#source p.mis.mis2.show_mis .t { background: #ffeeee; }
@media (prefers-color-scheme: dark) { #source p.mis.mis2.show_mis .t { background: #351b1b; } }
#source p.mis.mis2.show_mis .t:hover { background: #f2d2d2; }
@media (prefers-color-scheme: dark) { #source p.mis.mis2.show_mis .t:hover { background: #532323; } }
#source p.run .t { border-left: 0.2em solid #00dd00; }
#source p.run.show_run .t { background: #dfd; }
@media (prefers-color-scheme: dark) { #source p.run.show_run .t { background: #373d29; } }
#source p.run.show_run .t:hover { background: #d2f2d2; }
@media (prefers-color-scheme: dark) { #source p.run.show_run .t:hover { background: #404633; } }
#source p.run.run2 .t { border-left: 0.2em dotted #00dd00; }
#source p.run.run2.show_run .t { background: #eeffee; }
@media (prefers-color-scheme: dark) { #source p.run.run2.show_run .t { background: #2b2e24; } }
#source p.run.run2.show_run .t:hover { background: #d2f2d2; }
@media (prefers-color-scheme: dark) { #source p.run.run2.show_run .t:hover { background: #404633; } }
#source p.exc .t { border-left: 0.2em solid #808080; }
#source p.exc.show_exc .t { background: #eee; }
@media (prefers-color-scheme: dark) { #source p.exc.show_exc .t { background: #333; } }
#source p.exc.show_exc .t:hover { background: #e2e2e2; }
@media (prefers-color-scheme: dark) { #source p.exc.show_exc .t:hover { background: #3c3c3c; } }
#source p.exc.exc2 .t { border-left: 0.2em dotted #808080; }
#source p.exc.exc2.show_exc .t { background: #f7f7f7; }
@media (prefers-color-scheme: dark) { #source p.exc.exc2.show_exc .t { background: #292929; } }
#source p.exc.exc2.show_exc .t:hover { background: #e2e2e2; }
@media (prefers-color-scheme: dark) { #source p.exc.exc2.show_exc .t:hover { background: #3c3c3c; } }
#source p.par .t { border-left: 0.2em solid #bbbb00; }
#source p.par.show_par .t { background: #ffa; }
@media (prefers-color-scheme: dark) { #source p.par.show_par .t { background: #650; } }
#source p.par.show_par .t:hover { background: #f2f2a2; }
@media (prefers-color-scheme: dark) { #source p.par.show_par .t:hover { background: #6d5d0c; } }
#source p.par.par2 .t { border-left: 0.2em dotted #bbbb00; }
#source p.par.par2.show_par .t { background: #ffffd5; }
@media (prefers-color-scheme: dark) { #source p.par.par2.show_par .t { background: #423a0f; } }
#source p.par.par2.show_par .t:hover { background: #f2f2a2; }
@media (prefers-color-scheme: dark) { #source p.par.par2.show_par .t:hover { background: #6d5d0c; } }
#source p .r { position: absolute; top: 0; right: 2.5em; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Ubuntu, Cantarell, "Helvetica Neue", sans-serif; }
#source p .annotate { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Ubuntu, Cantarell, "Helvetica Neue", sans-serif; color: #666; padding-right: .5em; }
@media (prefers-color-scheme: dark) { #source p .annotate { color: #ddd; } }
#source p .annotate.short:hover ~ .long { display: block; }
#source p .annotate.long { width: 30em; right: 2.5em; }
#source p input { display: none; }
#source p input ~ .r label.ctx { cursor: pointer; border-radius: .25em; }
#source p input ~ .r label.ctx::before { content: "โถ "; }
#source p input ~ .r label.ctx:hover { background: #e8f4ff; color: #666; }
@media (prefers-color-scheme: dark) { #source p input ~ .r label.ctx:hover { background: #0f3a42; } }
@media (prefers-color-scheme: dark) { #source p input ~ .r label.ctx:hover { color: #aaa; } }
#source p input:checked ~ .r label.ctx { background: #d0e8ff; color: #666; border-radius: .75em .75em 0 0; padding: 0 .5em; margin: -.25em 0; }
@media (prefers-color-scheme: dark) { #source p input:checked ~ .r label.ctx { background: #056; } }
@media (prefers-color-scheme: dark) { #source p input:checked ~ .r label.ctx { color: #aaa; } }
#source p input:checked ~ .r label.ctx::before { content: "โผ "; }
#source p input:checked ~ .ctxs { padding: .25em .5em; overflow-y: scroll; max-height: 10.5em; }
#source p label.ctx { color: #999; display: inline-block; padding: 0 .5em; font-size: .8333em; }
@media (prefers-color-scheme: dark) { #source p label.ctx { color: #777; } }
#source p .ctxs { display: block; max-height: 0; overflow-y: hidden; transition: all .2s; padding: 0 .5em; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Ubuntu, Cantarell, "Helvetica Neue", sans-serif; white-space: nowrap; background: #d0e8ff; border-radius: .25em; margin-right: 1.75em; text-align: right; }
@media (prefers-color-scheme: dark) { #source p .ctxs { background: #056; } }
#index { font-family: SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 0.875em; }
#index table.index { margin-left: -.5em; }
#index td, #index th { text-align: right; padding: .25em .5em; border-bottom: 1px solid #eee; }
@media (prefers-color-scheme: dark) { #index td, #index th { border-color: #333; } }
#index td.name, #index th.name { text-align: left; width: auto; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Ubuntu, Cantarell, "Helvetica Neue", sans-serif; min-width: 15em; }
#index th { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Ubuntu, Cantarell, "Helvetica Neue", sans-serif; font-style: italic; color: #333; cursor: pointer; }
@media (prefers-color-scheme: dark) { #index th { color: #ddd; } }
#index th:hover { background: #eee; }
@media (prefers-color-scheme: dark) { #index th:hover { background: #333; } }
#index th .arrows { color: #666; font-size: 85%; font-family: sans-serif; font-style: normal; pointer-events: none; }
#index th[aria-sort="ascending"], #index th[aria-sort="descending"] { white-space: nowrap; background: #eee; padding-left: .5em; }
@media (prefers-color-scheme: dark) { #index th[aria-sort="ascending"], #index th[aria-sort="descending"] { background: #333; } }
#index th[aria-sort="ascending"] .arrows::after { content: " โฒ"; }
#index th[aria-sort="descending"] .arrows::after { content: " โผ"; }
#index td.name { font-size: 1.15em; }
#index td.name a { text-decoration: none; color: inherit; }
#index td.name .no-noun { font-style: italic; }
#index tr.total td, #index tr.total_dynamic td { font-weight: bold; border-top: 1px solid #ccc; border-bottom: none; }
#index tr.region:hover { background: #eee; }
@media (prefers-color-scheme: dark) { #index tr.region:hover { background: #333; } }
#index tr.region:hover td.name { text-decoration: underline; color: inherit; }
#scroll_marker { position: fixed; z-index: 3; right: 0; top: 0; width: 16px; height: 100%; background: #fff; border-left: 1px solid #eee; will-change: transform; }
@media (prefers-color-scheme: dark) { #scroll_marker { background: #1e1e1e; } }
@media (prefers-color-scheme: dark) { #scroll_marker { border-color: #333; } }
#scroll_marker .marker { background: #ccc; position: absolute; min-height: 3px; width: 100%; }
@media (prefers-color-scheme: dark) { #scroll_marker .marker { background: #444; } }
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/htmlfiles/style.scss 0000644 0001751 0001751 00000050661 15073731535 020701 0 ustar 00runner runner /* Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 */
/* For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt */
// CSS styles for coverage.py HTML reports.
// When you edit this file, you need to run "make css" to get the CSS file
// generated, and then check in both the .scss and the .css files.
// When working on the file, this command is useful:
// sass --watch --style=compact --sourcemap=none --no-cache coverage/htmlfiles/style.scss:htmlcov/style.css
//
// OR you can process sass purely in python with `pip install pysass`, then:
// pysassc --style=compact coverage/htmlfiles/style.scss coverage/htmlfiles/style.css
// Ignore this comment, it's for the CSS output file:
/* Don't edit this .css file. Edit the .scss file instead! */
// Dimensions
$left-gutter: 3.5rem;
//
// Declare colors and variables
//
$font-normal: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
$font-code: SFMono-Regular, Menlo, Monaco, Consolas, monospace;
$off-button-lighten: 50%;
$hover-dark-amt: 95%;
$multi-dim-amt: 50%;
$focus-color: #007acc;
$mis-color: #ff0000;
$run-color: #00dd00;
$exc-color: #808080;
$par-color: #bbbb00;
$light-bg: #fff;
$light-fg: #000;
$light-gray1: #f8f8f8;
$light-gray2: #eee;
$light-gray3: #ccc;
$light-gray4: #999;
$light-gray5: #666;
$light-gray6: #333;
$light-pln-bg: $light-bg;
$light-mis-bg: #fdd;
$light-run-bg: #dfd;
$light-exc-bg: $light-gray2;
$light-par-bg: #ffa;
$light-token-com: #008000;
$light-token-str: #0451a5;
$light-context-bg-color: #d0e8ff;
$dark-bg: #1e1e1e;
$dark-fg: #eee;
$dark-gray1: #222;
$dark-gray2: #333;
$dark-gray3: #444;
$dark-gray4: #777;
$dark-gray5: #aaa;
$dark-gray6: #ddd;
$dark-pln-bg: $dark-bg;
$dark-mis-bg: #4b1818;
$dark-run-bg: #373d29;
$dark-exc-bg: $dark-gray2;
$dark-par-bg: #650;
$dark-token-com: #6a9955;
$dark-token-str: #9cdcfe;
$dark-context-bg-color: #056;
//
// Mixins and utilities
//
@mixin background-dark($color) {
@media (prefers-color-scheme: dark) {
background: $color;
}
}
@mixin color-dark($color) {
@media (prefers-color-scheme: dark) {
color: $color;
}
}
@mixin border-color-dark($color) {
@media (prefers-color-scheme: dark) {
border-color: $color;
}
}
// Add visual outline to navigable elements on focus improve accessibility.
@mixin focus-border {
&:active, &:focus {
outline: 2px dashed $focus-color;
}
}
@mixin button-shape {
font-family: inherit;
font-size: inherit;
border: 1px solid;
border-radius: .2em;
background: $light-gray2;
@include background-dark($dark-gray2);
color: inherit;
text-decoration: none;
padding: .1em .5em;
margin: 1px calc(.1em + 1px);
cursor: pointer;
border-color: $light-gray3;
@include border-color-dark($dark-gray3);
}
// Page-wide styles
html, body, h1, h2, h3, p, table, td, th {
margin: 0;
padding: 0;
border: 0;
font-weight: inherit;
font-style: inherit;
font-size: 100%;
font-family: inherit;
vertical-align: baseline;
}
// Set baseline grid to 16 pt.
body {
font-family: $font-normal;
font-size: 1em;
background: $light-bg;
color: $light-fg;
@include background-dark($dark-bg);
@include color-dark($dark-fg);
}
html>body {
font-size: 16px;
}
a {
@include focus-border;
}
p {
font-size: .875em;
line-height: 1.4em;
}
table {
border-collapse: collapse;
}
td {
vertical-align: top;
}
table tr.hidden {
display: none !important;
}
p#no_rows {
display: none;
font-size: 1.15em;
font-family: $font-normal;
}
a.nav {
text-decoration: none;
color: inherit;
&:hover {
text-decoration: underline;
color: inherit;
}
}
.hidden {
display: none;
}
// Page structure
header {
background: $light-gray1;
@include background-dark(black);
width: 100%;
z-index: 2;
border-bottom: 1px solid $light-gray3;
@include border-color-dark($dark-gray2);
.content {
padding: 1rem $left-gutter;
}
h2 {
margin-top: .5em;
font-size: 1em;
a.button {
@include button-shape;
&.current {
border: 2px solid;
background: $light-bg;
@include background-dark($dark-bg);
border-color: $light-gray4;
@include border-color-dark($dark-gray4);
cursor: default;
}
}
}
p.text {
margin: .5em 0 -.5em;
color: $light-gray5;
@include color-dark($dark-gray5);
font-style: italic;
}
&.sticky {
position: fixed;
left: 0;
right: 0;
height: 2.5em;
.text {
display: none;
}
h1, h2 {
font-size: 1em;
margin-top: 0;
display: inline-block;
}
.content {
padding: .5rem $left-gutter;
p {
font-size: 1em;
}
}
& ~ #source {
padding-top: 6.5em;
}
}
}
main {
position: relative;
z-index: 1;
}
footer {
margin: 1rem $left-gutter;
.content {
padding: 0;
color: $light-gray5;
@include color-dark($dark-gray5);
font-style: italic;
}
}
#index {
margin: 1rem 0 0 $left-gutter;
}
// Header styles
h1 {
font-size: 1.25em;
display: inline-block;
}
#filter_container {
float: right;
margin: 0 2em 0 0;
line-height: 1.66em;
#filter {
width: 10em;
padding: 0.2em 0.5em;
border: 2px solid $light-gray3;
background: $light-bg;
color: $light-fg;
@include border-color-dark($dark-gray3);
@include background-dark($dark-bg);
@include color-dark($dark-fg);
&:focus {
border-color: $focus-color;
}
}
:disabled ~ label{
color: $light-gray3;
@include color-dark($dark-gray3);
}
label {
font-size: .875em;
color: $light-gray5;
@include color-dark($dark-gray5);
}
}
header button {
@include button-shape;
@include focus-border;
&.run {
background: mix($light-run-bg, $light-bg, $off-button-lighten);
@include background-dark($dark-run-bg);
&.show_run {
background: $light-run-bg;
@include background-dark($dark-run-bg);
border: 2px solid $run-color;
margin: 0 .1em;
}
}
&.mis {
background: mix($light-mis-bg, $light-bg, $off-button-lighten);
@include background-dark($dark-mis-bg);
&.show_mis {
background: $light-mis-bg;
@include background-dark($dark-mis-bg);
border: 2px solid $mis-color;
margin: 0 .1em;
}
}
&.exc {
background: mix($light-exc-bg, $light-bg, $off-button-lighten);
@include background-dark($dark-exc-bg);
&.show_exc {
background: $light-exc-bg;
@include background-dark($dark-exc-bg);
border: 2px solid $exc-color;
margin: 0 .1em;
}
}
&.par {
background: mix($light-par-bg, $light-bg, $off-button-lighten);
@include background-dark($dark-par-bg);
&.show_par {
background: $light-par-bg;
@include background-dark($dark-par-bg);
border: 2px solid $par-color;
margin: 0 .1em;
}
}
}
// Yellow post-it things.
%popup {
display: none;
position: absolute;
z-index: 999;
background: #ffffcc;
border: 1px solid #888;
border-radius: .2em;
color: #333;
padding: .25em .5em;
}
// Yellow post-it's in the text listings.
%in-text-popup {
@extend %popup;
white-space: normal;
float: right;
top: 1.75em;
right: 1em;
height: auto;
}
// Help panel
#help_panel_wrapper {
float: right;
position: relative;
}
#keyboard_icon {
margin: 5px;
}
#help_panel_state {
display: none;
}
#help_panel {
@extend %popup;
top: 25px;
right: 0;
padding: .75em;
border: 1px solid #883;
color: #333;
.keyhelp p {
margin-top: .75em;
}
.legend {
font-style: italic;
margin-bottom: 1em;
}
.indexfile & {
width: 25em;
}
.pyfile & {
width: 18em;
}
#help_panel_state:checked ~ & {
display: block;
}
}
kbd {
border: 1px solid black;
border-color: #888 #333 #333 #888;
padding: .1em .35em;
font-family: $font-code;
font-weight: bold;
background: #eee;
border-radius: 3px;
}
// Source file styles
// The slim bar at the left edge of the source lines, colored by coverage.
$border-indicator-width: .2em;
#source {
padding: 1em 0 1em $left-gutter;
font-family: $font-code;
p {
// position relative makes position:absolute pop-ups appear in the right place.
position: relative;
white-space: pre;
* {
box-sizing: border-box;
}
.n {
float: left;
text-align: right;
width: $left-gutter;
box-sizing: border-box;
margin-left: -$left-gutter;
padding-right: 1em;
color: $light-gray4;
user-select: none;
@include color-dark($dark-gray4);
&.highlight {
background: #ffdd00;
}
a {
// Make anchors to the line scroll the line to be
// visible beneath the fixed-position header.
scroll-margin-top: 6em;
text-decoration: none;
color: $light-gray4;
@include color-dark($dark-gray4);
&:hover {
text-decoration: underline;
color: $light-gray4;
@include color-dark($dark-gray4);
}
}
}
.t {
display: inline-block;
width: 100%;
box-sizing: border-box;
margin-left: -.5em;
padding-left: .5em - $border-indicator-width;
border-left: $border-indicator-width solid $light-bg;
@include border-color-dark($dark-bg);
&:hover {
background: mix($light-pln-bg, $light-fg, $hover-dark-amt);
@include background-dark(mix($dark-pln-bg, $dark-fg, $hover-dark-amt));
& ~ .r .annotate.long {
display: block;
}
}
// Syntax coloring
.com {
color: $light-token-com;
@include color-dark($dark-token-com);
font-style: italic;
line-height: 1px;
}
.key {
font-weight: bold;
line-height: 1px;
}
.str, .fst {
color: $light-token-str;
@include color-dark($dark-token-str);
}
}
&.mis {
.t {
border-left: $border-indicator-width solid $mis-color;
}
&.show_mis .t {
background: $light-mis-bg;
@include background-dark($dark-mis-bg);
&:hover {
background: mix($light-mis-bg, $light-fg, $hover-dark-amt);
@include background-dark(mix($dark-mis-bg, $dark-fg, $hover-dark-amt));
}
}
&.mis2 {
.t {
border-left: $border-indicator-width dotted $mis-color;
}
&.show_mis .t {
background: mix($light-mis-bg, $light-bg, $multi-dim-amt);
@include background-dark(mix($dark-mis-bg, $dark-bg, $multi-dim-amt));
&:hover {
background: mix($light-mis-bg, $light-fg, $hover-dark-amt);
@include background-dark(mix($dark-mis-bg, $dark-fg, $hover-dark-amt));
}
}
}
}
&.run {
.t {
border-left: $border-indicator-width solid $run-color;
}
&.show_run .t {
background: $light-run-bg;
@include background-dark($dark-run-bg);
&:hover {
background: mix($light-run-bg, $light-fg, $hover-dark-amt);
@include background-dark(mix($dark-run-bg, $dark-fg, $hover-dark-amt));
}
}
&.run2 {
.t {
border-left: $border-indicator-width dotted $run-color;
}
&.show_run .t {
background: mix($light-run-bg, $light-bg, $multi-dim-amt);
@include background-dark(mix($dark-run-bg, $dark-bg, $multi-dim-amt));
&:hover {
background: mix($light-run-bg, $light-fg, $hover-dark-amt);
@include background-dark(mix($dark-run-bg, $dark-fg, $hover-dark-amt));
}
}
}
}
&.exc {
.t {
border-left: $border-indicator-width solid $exc-color;
}
&.show_exc .t {
background: $light-exc-bg;
@include background-dark($dark-exc-bg);
&:hover {
background: mix($light-exc-bg, $light-fg, $hover-dark-amt);
@include background-dark(mix($dark-exc-bg, $dark-fg, $hover-dark-amt));
}
}
&.exc2 {
.t {
border-left: $border-indicator-width dotted $exc-color;
}
&.show_exc .t {
background: mix($light-exc-bg, $light-bg, $multi-dim-amt);
@include background-dark(mix($dark-exc-bg, $dark-bg, $multi-dim-amt));
&:hover {
background: mix($light-exc-bg, $light-fg, $hover-dark-amt);
@include background-dark(mix($dark-exc-bg, $dark-fg, $hover-dark-amt));
}
}
}
}
&.par {
.t {
border-left: $border-indicator-width solid $par-color;
}
&.show_par .t {
background: $light-par-bg;
@include background-dark($dark-par-bg);
&:hover {
background: mix($light-par-bg, $light-fg, $hover-dark-amt);
@include background-dark(mix($dark-par-bg, $dark-fg, $hover-dark-amt));
}
}
&.par2 {
.t {
border-left: $border-indicator-width dotted $par-color;
}
&.show_par .t {
background: mix($light-par-bg, $light-bg, $multi-dim-amt);
@include background-dark(mix($dark-par-bg, $dark-bg, $multi-dim-amt));
&:hover {
background: mix($light-par-bg, $light-fg, $hover-dark-amt);
@include background-dark(mix($dark-par-bg, $dark-fg, $hover-dark-amt));
}
}
}
}
.r {
position: absolute;
top: 0;
right: 2.5em;
font-family: $font-normal;
}
.annotate {
font-family: $font-normal;
color: $light-gray5;
@include color-dark($dark-gray6);
padding-right: .5em;
&.short:hover ~ .long {
display: block;
}
&.long {
@extend %in-text-popup;
width: 30em;
right: 2.5em;
}
}
input {
display: none;
& ~ .r label.ctx {
cursor: pointer;
border-radius: .25em;
&::before {
content: "โถ ";
}
&:hover {
background: mix($light-context-bg-color, $light-bg, $off-button-lighten);
@include background-dark(mix($dark-context-bg-color, $dark-bg, $off-button-lighten));
color: $light-gray5;
@include color-dark($dark-gray5);
}
}
&:checked ~ .r label.ctx {
background: $light-context-bg-color;
@include background-dark($dark-context-bg-color);
color: $light-gray5;
@include color-dark($dark-gray5);
border-radius: .75em .75em 0 0;
padding: 0 .5em;
margin: -.25em 0;
&::before {
content: "โผ ";
}
}
&:checked ~ .ctxs {
padding: .25em .5em;
overflow-y: scroll;
max-height: 10.5em;
}
}
label.ctx {
color: $light-gray4;
@include color-dark($dark-gray4);
display: inline-block;
padding: 0 .5em;
font-size: .8333em; // 10/12
}
.ctxs {
display: block;
max-height: 0;
overflow-y: hidden;
transition: all .2s;
padding: 0 .5em;
font-family: $font-normal;
white-space: nowrap;
background: $light-context-bg-color;
@include background-dark($dark-context-bg-color);
border-radius: .25em;
margin-right: 1.75em;
text-align: right;
}
}
}
// index styles
#index {
font-family: $font-code;
font-size: 0.875em;
table.index {
margin-left: -.5em;
}
td, th {
text-align: right;
padding: .25em .5em;
border-bottom: 1px solid $light-gray2;
@include border-color-dark($dark-gray2);
&.name {
text-align: left;
width: auto;
font-family: $font-normal;
min-width: 15em;
}
}
th {
font-family: $font-normal;
font-style: italic;
color: $light-gray6;
@include color-dark($dark-gray6);
cursor: pointer;
&:hover {
background: $light-gray2;
@include background-dark($dark-gray2);
}
.arrows {
color: #666;
font-size: 85%;
font-family: sans-serif;
font-style: normal;
pointer-events: none;
}
&[aria-sort="ascending"], &[aria-sort="descending"] {
white-space: nowrap;
background: $light-gray2;
@include background-dark($dark-gray2);
padding-left: .5em;
}
&[aria-sort="ascending"] .arrows::after {
content: " โฒ";
}
&[aria-sort="descending"] .arrows::after {
content: " โผ";
}
}
td.name {
font-size: 1.15em;
a {
text-decoration: none;
color: inherit;
}
& .no-noun {
font-style: italic;
}
}
tr.total td,
tr.total_dynamic td {
font-weight: bold;
border-top: 1px solid #ccc;
border-bottom: none;
}
tr.region:hover {
background: $light-gray2;
@include background-dark($dark-gray2);
td.name {
text-decoration: underline;
color: inherit;
}
}
}
// scroll marker styles
#scroll_marker {
position: fixed;
z-index: 3;
right: 0;
top: 0;
width: 16px;
height: 100%;
background: $light-bg;
border-left: 1px solid $light-gray2;
@include background-dark($dark-bg);
@include border-color-dark($dark-gray2);
will-change: transform; // for faster scrolling of fixed element in Chrome
.marker {
background: $light-gray3;
@include background-dark($dark-gray3);
position: absolute;
min-height: 3px;
width: 100%;
}
}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/inorout.py 0000644 0001751 0001751 00000057427 15073731535 016735 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Determining whether files are being measured/reported or not."""
from __future__ import annotations
import importlib.util
import inspect
import itertools
import os
import os.path
import platform
import re
import sys
import sysconfig
import traceback
from collections.abc import Iterable
from types import FrameType, ModuleType
from typing import TYPE_CHECKING, Any, cast
from coverage import env
from coverage.disposition import FileDisposition, disposition_init
from coverage.exceptions import ConfigError, CoverageException, PluginError
from coverage.files import (
GlobMatcher,
ModuleMatcher,
TreeMatcher,
canonical_filename,
find_python_files,
prep_patterns,
)
from coverage.misc import isolate_module, sys_modules_saved
from coverage.python import source_for_file, source_for_morf
from coverage.types import TDebugCtl, TFileDisposition, TMorf, TWarnFn
if TYPE_CHECKING:
from coverage.config import CoverageConfig
from coverage.plugin_support import Plugins
modules_we_happen_to_have: list[ModuleType] = [
inspect,
itertools,
os,
platform,
re,
sysconfig,
traceback,
]
if env.PYPY:
# Pypy has some unusual stuff in the "stdlib". Consider those locations
# when deciding where the stdlib is. These modules are not used for anything,
# they are modules importable from the pypy lib directories, so that we can
# find those directories.
import _pypy_irc_topic # pylint: disable=import-error
import _structseq # pylint: disable=import-error
modules_we_happen_to_have.extend([_structseq, _pypy_irc_topic])
os = isolate_module(os)
def canonical_path(morf: TMorf, directory: bool = False) -> str:
"""Return the canonical path of the module or file `morf`.
If the module is a package, then return its directory. If it is a
module, then return its file, unless `directory` is True, in which
case return its enclosing directory.
"""
morf_path = canonical_filename(source_for_morf(morf))
if morf_path.endswith("__init__.py") or directory:
morf_path = os.path.split(morf_path)[0]
return morf_path
def name_for_module(filename: str, frame: FrameType | None) -> str | None:
"""Get the name of the module for a filename and frame.
For configurability's sake, we allow __main__ modules to be matched by
their importable name.
If loaded via runpy (aka -m), we can usually recover the "original"
full dotted module name, otherwise, we resort to interpreting the
file name to get the module's name. In the case that the module name
can't be determined, None is returned.
"""
module_globals = frame.f_globals if frame is not None else {}
dunder_name: str | None = module_globals.get("__name__", None)
if isinstance(dunder_name, str) and dunder_name != "__main__":
# This is the usual case: an imported module.
return dunder_name
spec = module_globals.get("__spec__", None)
if spec:
fullname = spec.name
if isinstance(fullname, str) and fullname != "__main__":
# Module loaded via: runpy -m
return fullname
# Script as first argument to Python command line.
inspectedname = inspect.getmodulename(filename)
if inspectedname is not None:
return inspectedname
else:
return dunder_name
def module_is_namespace(mod: ModuleType) -> bool:
"""Is the module object `mod` a PEP420 namespace module?"""
return hasattr(mod, "__path__") and getattr(mod, "__file__", None) is None
def module_has_file(mod: ModuleType) -> bool:
"""Does the module object `mod` have an existing __file__ ?"""
mod__file__ = getattr(mod, "__file__", None)
if mod__file__ is None:
return False
return os.path.exists(mod__file__)
def file_and_path_for_module(modulename: str) -> tuple[str | None, list[str]]:
"""Find the file and search path for `modulename`.
Returns:
filename: The filename of the module, or None.
path: A list (possibly empty) of directories to find submodules in.
"""
filename = None
path = []
try:
spec = importlib.util.find_spec(modulename)
except Exception:
pass
else:
if spec is not None:
filename = spec.origin
path = list(spec.submodule_search_locations or ())
return filename, path
def add_stdlib_paths(paths: set[str]) -> None:
"""Add paths where the stdlib can be found to the set `paths`."""
# Look at where some standard modules are located. That's the
# indication for "installed with the interpreter". In some
# environments (virtualenv, for example), these modules may be
# spread across a few locations. Look at all the candidate modules
# we've imported, and take all the different ones.
for m in modules_we_happen_to_have:
if hasattr(m, "__file__"):
paths.add(canonical_path(m, directory=True))
def add_third_party_paths(paths: set[str]) -> None:
"""Add locations for third-party packages to the set `paths`."""
# Get the paths that sysconfig knows about.
scheme_names = set(sysconfig.get_scheme_names())
for scheme in scheme_names:
# https://foss.heptapod.net/pypy/pypy/-/issues/3433
better_scheme = "pypy_posix" if scheme == "pypy" else scheme
if os.name in better_scheme.split("_"):
config_paths = sysconfig.get_paths(scheme)
for path_name in ["platlib", "purelib", "scripts"]:
paths.add(config_paths[path_name])
def add_coverage_paths(paths: set[str]) -> None:
"""Add paths where coverage.py code can be found to the set `paths`."""
cover_path = canonical_path(__file__, directory=True)
paths.add(cover_path)
if env.TESTING:
# Don't include our own test code.
paths.add(os.path.join(cover_path, "tests"))
class InOrOut:
"""Machinery for determining what files to measure."""
def __init__(
self,
config: CoverageConfig,
warn: TWarnFn,
debug: TDebugCtl | None,
include_namespace_packages: bool,
) -> None:
self.warn = warn
self.debug = debug
self.include_namespace_packages = include_namespace_packages
self.source_pkgs: list[str] = []
self.source_pkgs.extend(config.source_pkgs)
self.source_dirs: list[str] = []
self.source_dirs.extend(config.source_dirs)
for src in config.source or []:
if os.path.isdir(src):
self.source_dirs.append(src)
else:
self.source_pkgs.append(src)
# Canonicalize everything in `source_dirs`.
# Also confirm that they actually are directories.
for i, src in enumerate(self.source_dirs):
if not os.path.isdir(src):
raise ConfigError(f"Source dir is not a directory: {src!r}")
self.source_dirs[i] = canonical_filename(src)
self.source_pkgs_unmatched = self.source_pkgs[:]
self.include = prep_patterns(config.run_include)
self.omit = prep_patterns(config.run_omit)
# The directories for files considered "installed with the interpreter".
self.pylib_paths: set[str] = set()
if not config.cover_pylib:
add_stdlib_paths(self.pylib_paths)
# To avoid tracing the coverage.py code itself, we skip anything
# located where we are.
self.cover_paths: set[str] = set()
add_coverage_paths(self.cover_paths)
# Find where third-party packages are installed.
self.third_paths: set[str] = set()
add_third_party_paths(self.third_paths)
def _debug(msg: str) -> None:
if self.debug:
self.debug.write(msg)
# The matchers for should_trace.
# Generally useful information
_debug("sys.path:" + "".join(f"\n {p}" for p in sys.path))
# Create the matchers we need for should_trace
self.source_match = None
self.source_pkgs_match = None
self.pylib_match = None
self.include_match = self.omit_match = None
if self.source_dirs or self.source_pkgs:
against = []
if self.source_dirs:
self.source_match = TreeMatcher(self.source_dirs, "source")
against.append(f"trees {self.source_match!r}")
if self.source_pkgs:
self.source_pkgs_match = ModuleMatcher(self.source_pkgs, "source_pkgs")
against.append(f"modules {self.source_pkgs_match!r}")
_debug("Source matching against " + " and ".join(against))
else:
if self.pylib_paths:
self.pylib_match = TreeMatcher(self.pylib_paths, "pylib")
_debug(f"Python stdlib matching: {self.pylib_match!r}")
if self.include:
self.include_match = GlobMatcher(self.include, "include")
_debug(f"Include matching: {self.include_match!r}")
if self.omit:
self.omit_match = GlobMatcher(self.omit, "omit")
_debug(f"Omit matching: {self.omit_match!r}")
self.cover_match = TreeMatcher(self.cover_paths, "coverage")
_debug(f"Coverage code matching: {self.cover_match!r}")
self.third_match = TreeMatcher(self.third_paths, "third")
_debug(f"Third-party lib matching: {self.third_match!r}")
# Check if the source we want to measure has been installed as a
# third-party package.
# Is the source inside a third-party area?
self.source_in_third_paths = set()
with sys_modules_saved():
for pkg in self.source_pkgs:
try:
modfile, path = file_and_path_for_module(pkg)
_debug(f"Imported source package {pkg!r} as {modfile!r}")
except CoverageException as exc:
_debug(f"Couldn't import source package {pkg!r}: {exc}")
continue
if modfile:
if self.third_match.match(modfile):
_debug(
f"Source in third-party: source_pkg {pkg!r} at {modfile!r}",
)
self.source_in_third_paths.add(canonical_path(source_for_file(modfile)))
else:
for pathdir in path:
if self.third_match.match(pathdir):
_debug(
f"Source in third-party: {pkg!r} path directory at {pathdir!r}",
)
self.source_in_third_paths.add(pathdir)
for src in self.source_dirs:
if self.third_match.match(src):
_debug(f"Source in third-party: source directory {src!r}")
self.source_in_third_paths.add(src)
self.source_in_third_match = TreeMatcher(self.source_in_third_paths, "source_in_third")
_debug(f"Source in third-party matching: {self.source_in_third_match}")
self.plugins: Plugins
self.disp_class: type[TFileDisposition] = FileDisposition
def should_trace(self, filename: str, frame: FrameType | None = None) -> TFileDisposition:
"""Decide whether to trace execution in `filename`, with a reason.
This function is called from the trace function. As each new file name
is encountered, this function determines whether it is traced or not.
Returns a FileDisposition object.
"""
original_filename = filename
disp = disposition_init(self.disp_class, filename)
def nope(disp: TFileDisposition, reason: str) -> TFileDisposition:
"""Simple helper to make it easy to return NO."""
disp.trace = False
disp.reason = reason
return disp
if original_filename.startswith("<"):
return nope(disp, "original file name is not real")
if frame is not None:
# Compiled Python files have two file names: frame.f_code.co_filename is
# the file name at the time the .pyc was compiled. The second name is
# __file__, which is where the .pyc was actually loaded from. Since
# .pyc files can be moved after compilation (for example, by being
# installed), we look for __file__ in the frame and prefer it to the
# co_filename value.
dunder_file = frame.f_globals and frame.f_globals.get("__file__")
if dunder_file:
# Danger: __file__ can (rarely?) be of type Path.
filename = source_for_file(str(dunder_file))
if original_filename and not original_filename.startswith("<"):
orig = os.path.basename(original_filename)
if orig != os.path.basename(filename):
# Files shouldn't be renamed when moved. This happens when
# exec'ing code. If it seems like something is wrong with
# the frame's file name, then just use the original.
filename = original_filename
if not filename:
# Empty string is pretty useless.
return nope(disp, "empty string isn't a file name")
if filename.startswith("memory:"):
return nope(disp, "memory isn't traceable")
if filename.startswith("<"):
# Lots of non-file execution is represented with artificial
# file names like "", "", or
# "". Don't ever trace these executions, since we
# can't do anything with the data later anyway.
return nope(disp, "file name is not real")
canonical = canonical_filename(filename)
disp.canonical_filename = canonical
# Try the plugins, see if they have an opinion about the file.
plugin = None
for plugin in self.plugins.file_tracers:
if not plugin._coverage_enabled:
continue
try:
file_tracer = plugin.file_tracer(canonical)
if file_tracer is not None:
file_tracer._coverage_plugin = plugin
disp.trace = True
disp.file_tracer = file_tracer
if file_tracer.has_dynamic_source_filename():
disp.has_dynamic_filename = True
else:
disp.source_filename = canonical_filename(
file_tracer.source_filename(),
)
break
except Exception:
plugin_name = plugin._coverage_plugin_name
tb = traceback.format_exc()
self.warn(f"Disabling plug-in {plugin_name!r} due to an exception:\n{tb}")
plugin._coverage_enabled = False
continue
else:
# No plugin wanted it: it's Python.
disp.trace = True
disp.source_filename = canonical
if not disp.has_dynamic_filename:
if not disp.source_filename:
raise PluginError(
f"Plugin {plugin!r} didn't set source_filename for '{disp.original_filename}'",
)
reason = self.check_include_omit_etc(disp.source_filename, frame)
if reason:
nope(disp, reason)
return disp
def check_include_omit_etc(self, filename: str, frame: FrameType | None) -> str | None:
"""Check a file name against the include, omit, etc, rules.
Returns a string or None. String means, don't trace, and is the reason
why. None means no reason found to not trace.
"""
modulename = name_for_module(filename, frame)
# If the user specified source or include, then that's authoritative
# about the outer bound of what to measure and we don't have to apply
# any canned exclusions. If they didn't, then we have to exclude the
# stdlib and coverage.py directories.
if self.source_match or self.source_pkgs_match:
extra = ""
ok = False
if self.source_pkgs_match:
if isinstance(modulename, str) and self.source_pkgs_match.match(modulename):
ok = True
if modulename in self.source_pkgs_unmatched:
self.source_pkgs_unmatched.remove(modulename)
else:
extra = f"module {modulename!r} "
if not ok and self.source_match:
if self.source_match.match(filename):
ok = True
if not ok:
return extra + "falls outside the --source spec"
if self.third_match.match(filename) and not self.source_in_third_match.match(filename):
return "inside --source, but is third-party"
elif self.include_match:
if not self.include_match.match(filename):
return "falls outside the --include trees"
else:
# We exclude the coverage.py code itself, since a little of it
# will be measured otherwise.
if self.cover_match.match(filename):
return "is part of coverage.py"
# If we aren't supposed to trace installed code, then check if this
# is near the Python standard library and skip it if so.
if self.pylib_match and self.pylib_match.match(filename):
return "is in the stdlib"
# Exclude anything in the third-party installation areas.
if self.third_match.match(filename):
return "is a third-party module"
# Check the file against the omit pattern.
if self.omit_match and self.omit_match.match(filename):
return "is inside an --omit pattern"
# No point tracing a file we can't later write to SQLite.
try:
filename.encode("utf-8")
except UnicodeEncodeError:
return "non-encodable filename"
# No reason found to skip this file.
return None
def warn_conflicting_settings(self) -> None:
"""Warn if there are settings that conflict."""
if self.include:
if self.source_dirs or self.source_pkgs:
self.warn("--include is ignored because --source is set", slug="include-ignored")
def warn_already_imported_files(self) -> None:
"""Warn if files have already been imported that we will be measuring."""
if self.include or self.source_dirs or self.source_pkgs:
warned = set()
for mod in list(sys.modules.values()):
filename = getattr(mod, "__file__", None)
if filename is None:
continue
if filename in warned:
continue
if len(getattr(mod, "__path__", ())) > 1:
# A namespace package, which confuses this code, so ignore it.
continue
disp = self.should_trace(filename)
if disp.has_dynamic_filename:
# A plugin with dynamic filenames: the Python file
# shouldn't cause a warning, since it won't be the subject
# of tracing anyway.
continue
if disp.trace:
msg = f"Already imported a file that will be measured: {filename}"
self.warn(msg, slug="already-imported")
warned.add(filename)
elif self.debug and self.debug.should("trace"):
self.debug.write(
"Didn't trace already imported file {!r}: {}".format(
disp.original_filename,
disp.reason,
),
)
def warn_unimported_source(self) -> None:
"""Warn about source packages that were of interest, but never traced."""
for pkg in self.source_pkgs_unmatched:
self._warn_about_unmeasured_code(pkg)
def _warn_about_unmeasured_code(self, pkg: str) -> None:
"""Warn about a package or module that we never traced.
`pkg` is a string, the name of the package or module.
"""
mod = sys.modules.get(pkg)
if mod is None:
self.warn(f"Module {pkg} was never imported.", slug="module-not-imported")
return
if module_is_namespace(mod):
# A namespace package. It's OK for this not to have been traced,
# since there is no code directly in it.
return
if not module_has_file(mod):
self.warn(f"Module {pkg} has no Python source.", slug="module-not-python")
return
# The module was in sys.modules, and seems like a module with code, but
# we never measured it. I guess that means it was imported before
# coverage even started.
msg = f"Module {pkg} was previously imported, but not measured"
self.warn(msg, slug="module-not-measured")
def find_possibly_unexecuted_files(self) -> Iterable[tuple[str, str | None]]:
"""Find files in the areas of interest that might be untraced.
Yields pairs: file path, and responsible plug-in name.
"""
for pkg in self.source_pkgs:
if pkg not in sys.modules or not module_has_file(sys.modules[pkg]):
continue
pkg_file = source_for_file(cast(str, sys.modules[pkg].__file__))
yield from self._find_executable_files(canonical_path(pkg_file))
for src in self.source_dirs:
yield from self._find_executable_files(src)
def _find_plugin_files(self, src_dir: str) -> Iterable[tuple[str, str]]:
"""Get executable files from the plugins."""
for plugin in self.plugins.file_tracers:
for x_file in plugin.find_executable_files(src_dir):
yield x_file, plugin._coverage_plugin_name
def _find_executable_files(self, src_dir: str) -> Iterable[tuple[str, str | None]]:
"""Find executable files in `src_dir`.
Search for files in `src_dir` that can be executed because they
are probably importable. Don't include ones that have been omitted
by the configuration.
Yield the file path, and the plugin name that handles the file.
"""
py_files = (
(py_file, None)
for py_file in find_python_files(src_dir, self.include_namespace_packages)
)
plugin_files = self._find_plugin_files(src_dir)
for file_path, plugin_name in itertools.chain(py_files, plugin_files):
file_path = canonical_filename(file_path)
if self.omit_match and self.omit_match.match(file_path):
# Turns out this file was omitted, so don't pull it back
# in as un-executed.
continue
yield file_path, plugin_name
def sys_info(self) -> Iterable[tuple[str, Any]]:
"""Our information for Coverage.sys_info.
Returns a list of (key, value) pairs.
"""
info = [
("coverage_paths", self.cover_paths),
("stdlib_paths", self.pylib_paths),
("third_party_paths", self.third_paths),
("source_in_third_party_paths", self.source_in_third_paths),
]
matcher_names = [
"source_match",
"source_pkgs_match",
"include_match",
"omit_match",
"cover_match",
"pylib_match",
"third_match",
"source_in_third_match",
]
for matcher_name in matcher_names:
matcher = getattr(self, matcher_name)
if matcher:
matcher_info = matcher.info()
else:
matcher_info = "-none-"
info.append((matcher_name, matcher_info))
return info
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/jsonreport.py 0000644 0001751 0001751 00000015633 15073731535 017434 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Json reporting for coverage.py"""
from __future__ import annotations
import datetime
import json
import sys
from collections.abc import Iterable
from typing import IO, TYPE_CHECKING, Any
from coverage import __version__
from coverage.report_core import get_analysis_to_report
from coverage.results import Analysis, AnalysisNarrower, Numbers
from coverage.types import TLineNo, TMorf
if TYPE_CHECKING:
from coverage import Coverage
from coverage.data import CoverageData
from coverage.plugin import FileReporter
# A type for data that can be JSON-serialized.
JsonObj = dict[str, Any]
# "Version 1" had no format number at all.
# 2: add the meta.format field.
# 3: add region information (functions, classes)
FORMAT_VERSION = 3
class JsonReporter:
"""A reporter for writing JSON coverage results."""
report_type = "JSON report"
def __init__(self, coverage: Coverage) -> None:
self.coverage = coverage
self.config = self.coverage.config
self.total = Numbers(self.config.precision)
self.report_data: JsonObj = {}
def make_summary(self, nums: Numbers) -> JsonObj:
"""Create a dict summarizing `nums`."""
return {
"covered_lines": nums.n_executed,
"num_statements": nums.n_statements,
"percent_covered": nums.pc_covered,
"percent_covered_display": nums.pc_covered_str,
"missing_lines": nums.n_missing,
"excluded_lines": nums.n_excluded,
}
def make_branch_summary(self, nums: Numbers) -> JsonObj:
"""Create a dict summarizing the branch info in `nums`."""
return {
"num_branches": nums.n_branches,
"num_partial_branches": nums.n_partial_branches,
"covered_branches": nums.n_executed_branches,
"missing_branches": nums.n_missing_branches,
}
def report(self, morfs: Iterable[TMorf] | None, outfile: IO[str]) -> float:
"""Generate a json report for `morfs`.
`morfs` is a list of modules or file names.
`outfile` is a file object to write the json to.
"""
outfile = outfile or sys.stdout
coverage_data = self.coverage.get_data()
coverage_data.set_query_contexts(self.config.report_contexts)
self.report_data["meta"] = {
"format": FORMAT_VERSION,
"version": __version__,
"timestamp": datetime.datetime.now().isoformat(),
"branch_coverage": coverage_data.has_arcs(),
"show_contexts": self.config.json_show_contexts,
}
measured_files = {}
for file_reporter, analysis in get_analysis_to_report(self.coverage, morfs):
measured_files[file_reporter.relative_filename()] = self.report_one_file(
coverage_data,
analysis,
file_reporter,
)
self.report_data["files"] = measured_files
self.report_data["totals"] = self.make_summary(self.total)
if coverage_data.has_arcs():
self.report_data["totals"].update(self.make_branch_summary(self.total))
json.dump(
self.report_data,
outfile,
indent=(4 if self.config.json_pretty_print else None),
)
return self.total.n_statements and self.total.pc_covered
def report_one_file(
self, coverage_data: CoverageData, analysis: Analysis, file_reporter: FileReporter
) -> JsonObj:
"""Extract the relevant report data for a single file."""
nums = analysis.numbers
self.total += nums
summary = self.make_summary(nums)
reported_file: JsonObj = {
"executed_lines": sorted(analysis.executed),
"summary": summary,
"missing_lines": sorted(analysis.missing),
"excluded_lines": sorted(analysis.excluded),
}
if self.config.json_show_contexts:
reported_file["contexts"] = coverage_data.contexts_by_lineno(analysis.filename)
if coverage_data.has_arcs():
summary.update(self.make_branch_summary(nums))
reported_file["executed_branches"] = list(
_convert_branch_arcs(analysis.executed_branch_arcs()),
)
reported_file["missing_branches"] = list(
_convert_branch_arcs(analysis.missing_branch_arcs()),
)
num_lines = len(file_reporter.source().splitlines())
regions = file_reporter.code_regions()
for noun, plural in file_reporter.code_region_kinds():
outside_lines = set(range(1, num_lines + 1))
for region in regions:
if region.kind != noun:
continue
outside_lines -= region.lines
narrower = AnalysisNarrower(analysis)
narrower.add_regions(r.lines for r in regions if r.kind == noun)
narrower.add_regions([outside_lines])
reported_file[plural] = region_data = {}
for region in regions:
if region.kind != noun:
continue
region_data[region.name] = self.make_region_data(
coverage_data,
narrower.narrow(region.lines),
)
region_data[""] = self.make_region_data(
coverage_data,
narrower.narrow(outside_lines),
)
return reported_file
def make_region_data(self, coverage_data: CoverageData, narrowed_analysis: Analysis) -> JsonObj:
"""Create the data object for one region of a file."""
narrowed_nums = narrowed_analysis.numbers
narrowed_summary = self.make_summary(narrowed_nums)
this_region = {
"executed_lines": sorted(narrowed_analysis.executed),
"summary": narrowed_summary,
"missing_lines": sorted(narrowed_analysis.missing),
"excluded_lines": sorted(narrowed_analysis.excluded),
}
if self.config.json_show_contexts:
contexts = coverage_data.contexts_by_lineno(narrowed_analysis.filename)
this_region["contexts"] = contexts
if coverage_data.has_arcs():
narrowed_summary.update(self.make_branch_summary(narrowed_nums))
this_region["executed_branches"] = list(
_convert_branch_arcs(narrowed_analysis.executed_branch_arcs()),
)
this_region["missing_branches"] = list(
_convert_branch_arcs(narrowed_analysis.missing_branch_arcs()),
)
return this_region
def _convert_branch_arcs(
branch_arcs: dict[TLineNo, list[TLineNo]],
) -> Iterable[tuple[TLineNo, TLineNo]]:
"""Convert branch arcs to a list of two-element tuples."""
for source, targets in branch_arcs.items():
for target in targets:
yield source, target
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/lcovreport.py 0000644 0001751 0001751 00000017300 15073731535 017417 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""LCOV reporting for coverage.py."""
from __future__ import annotations
import base64
import hashlib
import sys
from collections.abc import Iterable
from typing import IO, TYPE_CHECKING
from coverage.plugin import FileReporter
from coverage.report_core import get_analysis_to_report
from coverage.results import Analysis, AnalysisNarrower, Numbers
from coverage.types import TMorf
if TYPE_CHECKING:
from coverage import Coverage
def line_hash(line: str) -> str:
"""Produce a hash of a source line for use in the LCOV file."""
# The LCOV file format optionally allows each line to be MD5ed as a
# fingerprint of the file. This is not a security use. Some security
# scanners raise alarms about the use of MD5 here, but it is a false
# positive. This is not a security concern.
# The unusual encoding of the MD5 hash, as a base64 sequence with the
# trailing = signs stripped, is specified by the LCOV file format.
hashed = hashlib.md5(line.encode("utf-8"), usedforsecurity=False).digest()
return base64.b64encode(hashed).decode("ascii").rstrip("=")
def lcov_lines(
analysis: Analysis,
lines: list[int],
source_lines: list[str],
outfile: IO[str],
) -> None:
"""Emit line coverage records for an analyzed file."""
hash_suffix = ""
for line in lines:
if source_lines:
hash_suffix = "," + line_hash(source_lines[line - 1])
# Q: can we get info about the number of times a statement is
# executed? If so, that should be recorded here.
hit = int(line not in analysis.missing)
outfile.write(f"DA:{line},{hit}{hash_suffix}\n")
if analysis.numbers.n_statements > 0:
outfile.write(f"LF:{analysis.numbers.n_statements}\n")
outfile.write(f"LH:{analysis.numbers.n_executed}\n")
def lcov_functions(
fr: FileReporter,
file_analysis: Analysis,
outfile: IO[str],
) -> None:
"""Emit function coverage records for an analyzed file."""
# lcov 2.2 introduces a new format for function coverage records.
# We continue to generate the old format because we don't know what
# version of the lcov tools will be used to read this report.
# "and region.lines" below avoids a crash due to a bug in PyPy 3.8
# where, for whatever reason, when collecting data in --branch mode,
# top-level functions have an empty lines array. Instead we just don't
# emit function records for those.
# suppressions because of https://github.com/pylint-dev/pylint/issues/9923
functions = [
(
min(region.start, min(region.lines)), # pylint: disable=nested-min-max
max(region.start, max(region.lines)), # pylint: disable=nested-min-max
region,
)
for region in fr.code_regions()
if region.kind == "function" and region.lines
]
if not functions:
return
narrower = AnalysisNarrower(file_analysis)
narrower.add_regions(r.lines for _, _, r in functions)
functions.sort()
functions_hit = 0
for first_line, last_line, region in functions:
# A function counts as having been executed if any of it has been
# executed.
analysis = narrower.narrow(region.lines)
hit = int(analysis.numbers.n_executed > 0)
functions_hit += hit
outfile.write(f"FN:{first_line},{last_line},{region.name}\n")
outfile.write(f"FNDA:{hit},{region.name}\n")
outfile.write(f"FNF:{len(functions)}\n")
outfile.write(f"FNH:{functions_hit}\n")
def lcov_arcs(
fr: FileReporter,
analysis: Analysis,
lines: list[int],
outfile: IO[str],
) -> None:
"""Emit branch coverage records for an analyzed file."""
branch_stats = analysis.branch_stats()
executed_arcs = analysis.executed_branch_arcs()
missing_arcs = analysis.missing_branch_arcs()
for line in lines:
if line not in branch_stats:
continue
# This is only one of several possible ways to map our sets of executed
# and not-executed arcs to BRDA codes. It seems to produce reasonable
# results when fed through genhtml.
_, taken = branch_stats[line]
if taken == 0:
# When _none_ of the out arcs from 'line' were executed,
# it can mean the line always raised an exception.
assert len(executed_arcs[line]) == 0
destinations = [(dst, "-") for dst in missing_arcs[line]]
else:
# Q: can we get counts of the number of times each arc was executed?
# branch_stats has "total" and "taken" counts for each branch,
# but it doesn't have "taken" broken down by destination.
destinations = [(dst, "1") for dst in executed_arcs[line]]
destinations.extend((dst, "0") for dst in missing_arcs[line])
# Sort exit arcs after normal arcs. Exit arcs typically come from
# an if statement, at the end of a function, with no else clause.
# This structure reads like you're jumping to the end of the function
# when the conditional expression is false, so it should be presented
# as the second alternative for the branch, after the alternative that
# enters the if clause.
destinations.sort(key=lambda d: (d[0] < 0, d))
for dst, hit in destinations:
branch = fr.arc_description(line, dst)
outfile.write(f"BRDA:{line},0,{branch},{hit}\n")
# Summary of the branch coverage.
brf = sum(t for t, k in branch_stats.values())
brh = brf - sum(t - k for t, k in branch_stats.values())
if brf > 0:
outfile.write(f"BRF:{brf}\n")
outfile.write(f"BRH:{brh}\n")
class LcovReporter:
"""A reporter for writing LCOV coverage reports."""
report_type = "LCOV report"
def __init__(self, coverage: Coverage) -> None:
self.coverage = coverage
self.config = coverage.config
self.total = Numbers(self.coverage.config.precision)
def report(self, morfs: Iterable[TMorf] | None, outfile: IO[str]) -> float:
"""Renders the full lcov report.
`morfs` is a list of modules or filenames
outfile is the file object to write the file into.
"""
self.coverage.get_data()
outfile = outfile or sys.stdout
# ensure file records are sorted by the _relative_ filename, not the full path
to_report = [
(fr.relative_filename(), fr, analysis)
for fr, analysis in get_analysis_to_report(self.coverage, morfs)
]
to_report.sort()
for fname, fr, analysis in to_report:
self.total += analysis.numbers
self.lcov_file(fname, fr, analysis, outfile)
return self.total.n_statements and self.total.pc_covered
def lcov_file(
self,
rel_fname: str,
fr: FileReporter,
analysis: Analysis,
outfile: IO[str],
) -> None:
"""Produces the lcov data for a single file.
This currently supports both line and branch coverage,
however function coverage is not supported.
"""
if analysis.numbers.n_statements == 0:
if self.config.skip_empty:
return
outfile.write(f"SF:{rel_fname}\n")
lines = sorted(analysis.statements)
if self.config.lcov_line_checksums:
source_lines = fr.source().splitlines()
else:
source_lines = []
lcov_lines(analysis, lines, source_lines, outfile)
lcov_functions(fr, analysis, outfile)
if analysis.has_arcs:
lcov_arcs(fr, analysis, lines, outfile)
outfile.write("end_of_record\n")
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/misc.py 0000644 0001751 0001751 00000026031 15073731535 016154 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Miscellaneous stuff for coverage.py."""
from __future__ import annotations
import contextlib
import datetime
import errno
import functools
import hashlib
import importlib
import importlib.util
import inspect
import os
import os.path
import re
import sys
import types
from collections.abc import Iterable, Iterator, Mapping, Sequence
from types import ModuleType
from typing import Any, NoReturn, TypeVar
# In 6.0, the exceptions moved from misc.py to exceptions.py. But a number of
# other packages were importing the exceptions from misc, so import them here.
# pylint: disable=unused-wildcard-import
from coverage.exceptions import * # pylint: disable=wildcard-import
from coverage.exceptions import CoverageException
from coverage.types import TArc
ISOLATED_MODULES: dict[ModuleType, ModuleType] = {}
def isolate_module(mod: ModuleType) -> ModuleType:
"""Copy a module so that we are isolated from aggressive mocking.
If a test suite mocks os.path.exists (for example), and then we need to use
it during the test, everything will get tangled up if we use their mock.
Making a copy of the module when we import it will isolate coverage.py from
those complications.
"""
if mod not in ISOLATED_MODULES:
new_mod = types.ModuleType(mod.__name__)
ISOLATED_MODULES[mod] = new_mod
for name in dir(mod):
value = getattr(mod, name)
if isinstance(value, types.ModuleType):
value = isolate_module(value)
setattr(new_mod, name, value)
return ISOLATED_MODULES[mod]
os = isolate_module(os)
class SysModuleSaver:
"""Saves the contents of sys.modules, and removes new modules later."""
def __init__(self) -> None:
self.old_modules = set(sys.modules)
def restore(self) -> None:
"""Remove any modules imported since this object started."""
new_modules = set(sys.modules) - self.old_modules
for m in new_modules:
del sys.modules[m]
@contextlib.contextmanager
def sys_modules_saved() -> Iterator[None]:
"""A context manager to remove any modules imported during a block."""
saver = SysModuleSaver()
try:
yield
finally:
saver.restore()
def import_third_party(modname: str) -> tuple[ModuleType, bool]:
"""Import a third-party module we need, but might not be installed.
This also cleans out the module after the import, so that coverage won't
appear to have imported it. This lets the third party use coverage for
their own tests.
Arguments:
modname (str): the name of the module to import.
Returns:
The imported module, and a boolean indicating if the module could be imported.
If the boolean is False, the module returned is not the one you want: don't use it.
"""
with sys_modules_saved():
try:
return importlib.import_module(modname), True
except ImportError:
return sys, False
def nice_pair(pair: TArc) -> str:
"""Make a nice string representation of a pair of numbers.
If the numbers are equal, just return the number, otherwise return the pair
with a dash between them, indicating the range.
"""
start, end = pair
if start == end:
return f"{start}"
else:
return f"{start}-{end}"
def bool_or_none(b: Any) -> bool | None:
"""Return bool(b), but preserve None."""
if b is None:
return None
else:
return bool(b)
def join_regex(regexes: Iterable[str]) -> str:
"""Combine a series of regex strings into one that matches any of them."""
regexes = list(regexes)
if len(regexes) == 1:
return regexes[0]
else:
return "|".join(f"(?:{r})" for r in regexes)
def file_be_gone(path: str) -> None:
"""Remove a file, and don't get annoyed if it doesn't exist."""
try:
os.remove(path)
except OSError as e:
if e.errno != errno.ENOENT:
raise
def ensure_dir(directory: str) -> None:
"""Make sure the directory exists.
If `directory` is None or empty, do nothing.
"""
if directory:
os.makedirs(directory, exist_ok=True)
def ensure_dir_for_file(path: str) -> None:
"""Make sure the directory for the path exists."""
ensure_dir(os.path.dirname(path))
class Hasher:
"""Hashes Python data for fingerprinting."""
def __init__(self) -> None:
self.hash = hashlib.new("sha3_256", usedforsecurity=False)
def update(self, v: Any) -> None:
"""Add `v` to the hash, recursively if needed."""
self.hash.update(str(type(v)).encode("utf-8"))
match v:
case None:
pass
case str():
self.hash.update(v.encode("utf-8"))
case bytes():
self.hash.update(v)
case int() | float():
self.hash.update(str(v).encode("utf-8"))
case tuple() | list():
for e in v:
self.update(e)
case dict():
keys = v.keys()
for k in sorted(keys):
self.update(k)
self.update(v[k])
case _:
for k in dir(v):
if k.startswith("__"):
continue
a = getattr(v, k)
if inspect.isroutine(a):
continue
self.update(k)
self.update(a)
self.hash.update(b".")
def hexdigest(self) -> str:
"""Retrieve the hex digest of the hash."""
return self.hash.hexdigest()[:32]
def _needs_to_implement(that: Any, func_name: str) -> NoReturn:
"""Helper to raise NotImplementedError in interface stubs."""
if hasattr(that, "_coverage_plugin_name"):
thing = "Plugin"
name = that._coverage_plugin_name
else:
thing = "Class"
klass = that.__class__
name = f"{klass.__module__}.{klass.__name__}"
raise NotImplementedError(
f"{thing} {name!r} needs to implement {func_name}()",
)
class DefaultValue:
"""A sentinel object to use for unusual default-value needs.
Construct with a string that will be used as the repr, for display in help
and Sphinx output.
"""
def __init__(self, display_as: str) -> None:
self.display_as = display_as
def __repr__(self) -> str:
return self.display_as
def substitute_variables(text: str, variables: Mapping[str, str]) -> str:
"""Substitute ``${VAR}`` variables in `text` with their values.
Variables in the text can take a number of shell-inspired forms::
$VAR
${VAR}
${VAR?} strict: an error if VAR isn't defined.
${VAR-missing} defaulted: "missing" if VAR isn't defined.
$$ just a dollar sign.
`variables` is a dictionary of variable values.
Returns the resulting text with values substituted.
"""
dollar_pattern = r"""(?x) # Use extended regex syntax
\$ # A dollar sign,
(?: # then
(?P \$ ) | # a dollar sign, or
(?P \w+ ) | # a plain word, or
\{ # a {-wrapped
(?P \w+ ) # word,
(?: # either
(?P \? ) | # with a strict marker
-(?P [^}]* ) # or a default value
)? # maybe.
}
)
"""
dollar_groups = ("dollar", "word1", "word2")
def dollar_replace(match: re.Match[str]) -> str:
"""Called for each $replacement."""
# Only one of the dollar_groups will have matched, just get its text.
word = next(g for g in match.group(*dollar_groups) if g) # pragma: always breaks
if word == "$":
return "$"
elif word in variables:
return variables[word]
elif match["strict"]:
msg = f"Variable {word} is undefined: {text!r}"
raise CoverageException(msg)
else:
return match["defval"]
text = re.sub(dollar_pattern, dollar_replace, text)
return text
def format_local_datetime(dt: datetime.datetime) -> str:
"""Return a string with local timezone representing the date."""
return dt.astimezone().strftime("%Y-%m-%d %H:%M %z")
def import_local_file(modname: str, modfile: str | None = None) -> ModuleType:
"""Import a local file as a module.
Opens a file in the current directory named `modname`.py, imports it
as `modname`, and returns the module object. `modfile` is the file to
import if it isn't in the current directory.
"""
if modfile is None:
modfile = modname + ".py"
spec = importlib.util.spec_from_file_location(modname, modfile)
assert spec is not None
mod = importlib.util.module_from_spec(spec)
sys.modules[modname] = mod
assert spec.loader is not None
spec.loader.exec_module(mod)
return mod
@functools.cache
def _human_key(s: str) -> tuple[list[str | int], str]:
"""Turn a string into a list of string and number chunks.
"z23a" -> (["z", 23, "a"], "z23a")
The original string is appended as a last value to ensure the
key is unique enough so that "x1y" and "x001y" can be distinguished.
"""
def tryint(s: str) -> str | int:
"""If `s` is a number, return an int, else `s` unchanged."""
try:
return int(s)
except ValueError:
return s
return ([tryint(c) for c in re.split(r"(\d+)", s)], s)
def human_sorted(strings: Iterable[str]) -> list[str]:
"""Sort the given iterable of strings the way that humans expect.
Numeric components in the strings are sorted as numbers.
Returns the sorted list.
"""
return sorted(strings, key=_human_key)
SortableItem = TypeVar("SortableItem", bound=Sequence[Any])
def human_sorted_items(
items: Iterable[SortableItem],
reverse: bool = False,
) -> list[SortableItem]:
"""Sort (string, ...) items the way humans expect.
The elements of `items` can be any tuple/list. They'll be sorted by the
first element (a string), with ties broken by the remaining elements.
Returns the sorted list of items.
"""
return sorted(items, key=lambda item: (_human_key(item[0]), *item[1:]), reverse=reverse)
def plural(n: int, thing: str = "", things: str = "") -> str:
"""Pluralize a word.
If n is 1, return thing. Otherwise return things, or thing+s.
"""
if n == 1:
return thing
else:
return things or (thing + "s")
def stdout_link(text: str, url: str) -> str:
"""Format text+url as a clickable link for stdout.
If attached to a terminal, use escape sequences. Otherwise, just return
the text.
"""
if hasattr(sys.stdout, "isatty") and sys.stdout.isatty():
return f"\033]8;;{url}\a{text}\033]8;;\a"
else:
return text
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/multiproc.py 0000644 0001751 0001751 00000010115 15073731535 017233 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Monkey-patching to add multiprocessing support for coverage.py"""
from __future__ import annotations
import multiprocessing
import multiprocessing.process
import os
import os.path
import sys
import traceback
from typing import Any
from coverage.debug import DebugControl
# An attribute that will be set on the module to indicate that it has been
# monkey-patched.
PATCHED_MARKER = "_coverage$patched"
OriginalProcess = multiprocessing.process.BaseProcess
original_bootstrap = OriginalProcess._bootstrap # type: ignore[attr-defined]
class ProcessWithCoverage(OriginalProcess): # pylint: disable=abstract-method
"""A replacement for multiprocess.Process that starts coverage."""
def _bootstrap(self, *args, **kwargs): # type: ignore[no-untyped-def]
"""Wrapper around _bootstrap to start coverage."""
debug: DebugControl | None = None
try:
from coverage import Coverage # avoid circular import
cov = Coverage(data_suffix=True, auto_data=True)
cov._warn_preimported_source = False
cov.start()
_debug = cov._debug
assert _debug is not None
if _debug.should("multiproc"):
debug = _debug
if debug:
debug.write("Calling multiprocessing bootstrap")
except Exception:
print("Exception during multiprocessing bootstrap init:", file=sys.stderr)
traceback.print_exc(file=sys.stderr)
sys.stderr.flush()
raise
try:
return original_bootstrap(self, *args, **kwargs)
finally:
if debug:
debug.write("Finished multiprocessing bootstrap")
try:
cov.stop()
cov.save()
except Exception as exc:
if debug:
debug.write("Exception during multiprocessing bootstrap cleanup", exc=exc)
raise
if debug:
debug.write("Saved multiprocessing data")
class Stowaway:
"""An object to pickle, so when it is unpickled, it can apply the monkey-patch."""
def __init__(self, rcfile: str) -> None:
self.rcfile = rcfile
def __getstate__(self) -> dict[str, str]:
return {"rcfile": self.rcfile}
def __setstate__(self, state: dict[str, str]) -> None:
patch_multiprocessing(state["rcfile"])
def patch_multiprocessing(rcfile: str) -> None:
"""Monkey-patch the multiprocessing module.
This enables coverage measurement of processes started by multiprocessing.
This involves aggressive monkey-patching.
`rcfile` is the path to the rcfile being used.
"""
if hasattr(multiprocessing, PATCHED_MARKER):
return
OriginalProcess._bootstrap = ProcessWithCoverage._bootstrap # type: ignore[attr-defined]
# Set the value in ProcessWithCoverage that will be pickled into the child
# process.
os.environ["COVERAGE_RCFILE"] = os.path.abspath(rcfile)
# When spawning processes rather than forking them, we have no state in the
# new process. We sneak in there with a Stowaway: we stuff one of our own
# objects into the data that gets pickled and sent to the subprocess. When
# the Stowaway is unpickled, its __setstate__ method is called, which
# re-applies the monkey-patch.
# Windows only spawns, so this is needed to keep Windows working.
try:
from multiprocessing import spawn
original_get_preparation_data = spawn.get_preparation_data
except (ImportError, AttributeError):
pass
else:
def get_preparation_data_with_stowaway(name: str) -> dict[str, Any]:
"""Get the original preparation data, and also insert our stowaway."""
d = original_get_preparation_data(name)
d["stowaway"] = Stowaway(rcfile)
return d
spawn.get_preparation_data = get_preparation_data_with_stowaway
setattr(multiprocessing, PATCHED_MARKER, True)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/numbits.py 0000644 0001751 0001751 00000011077 15073731535 016706 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""
Functions to manipulate packed binary representations of number sets.
To save space, coverage stores sets of line numbers in SQLite using a packed
binary representation called a numbits. A numbits is a set of positive
integers.
A numbits is stored as a blob in the database. The exact meaning of the bytes
in the blobs should be considered an implementation detail that might change in
the future. Use these functions to work with those binary blobs of data.
"""
from __future__ import annotations
import json
import sqlite3
from collections.abc import Iterable
from itertools import zip_longest
def nums_to_numbits(nums: Iterable[int]) -> bytes:
"""Convert `nums` into a numbits.
Arguments:
nums: a reusable iterable of integers, the line numbers to store.
Returns:
A binary blob.
"""
try:
nbytes = max(nums) // 8 + 1
except ValueError:
# nums was empty.
return b""
b = bytearray(nbytes)
for num in nums:
b[num // 8] |= 1 << num % 8
return bytes(b)
def numbits_to_nums(numbits: bytes) -> list[int]:
"""Convert a numbits into a list of numbers.
Arguments:
numbits: a binary blob, the packed number set.
Returns:
A list of ints.
When registered as a SQLite function by :func:`register_sqlite_functions`,
this returns a string, a JSON-encoded list of ints.
"""
nums = []
for byte_i, byte in enumerate(numbits):
for bit_i in range(8):
if byte & (1 << bit_i):
nums.append(byte_i * 8 + bit_i)
return nums
def numbits_union(numbits1: bytes, numbits2: bytes) -> bytes:
"""Compute the union of two numbits.
Returns:
A new numbits, the union of `numbits1` and `numbits2`.
"""
byte_pairs = zip_longest(numbits1, numbits2, fillvalue=0)
return bytes(b1 | b2 for b1, b2 in byte_pairs)
def numbits_intersection(numbits1: bytes, numbits2: bytes) -> bytes:
"""Compute the intersection of two numbits.
Returns:
A new numbits, the intersection `numbits1` and `numbits2`.
"""
byte_pairs = zip_longest(numbits1, numbits2, fillvalue=0)
intersection_bytes = bytes(b1 & b2 for b1, b2 in byte_pairs)
return intersection_bytes.rstrip(b"\0")
def numbits_any_intersection(numbits1: bytes, numbits2: bytes) -> bool:
"""Is there any number that appears in both numbits?
Determine whether two number sets have a non-empty intersection. This is
faster than computing the intersection.
Returns:
A bool, True if there is any number in both `numbits1` and `numbits2`.
"""
byte_pairs = zip_longest(numbits1, numbits2, fillvalue=0)
return any(b1 & b2 for b1, b2 in byte_pairs)
def num_in_numbits(num: int, numbits: bytes) -> bool:
"""Does the integer `num` appear in `numbits`?
Returns:
A bool, True if `num` is a member of `numbits`.
"""
nbyte, nbit = divmod(num, 8)
if nbyte >= len(numbits):
return False
return bool(numbits[nbyte] & (1 << nbit))
def register_sqlite_functions(connection: sqlite3.Connection) -> None:
"""
Define numbits functions in a SQLite connection.
This defines these functions for use in SQLite statements:
* :func:`numbits_union`
* :func:`numbits_intersection`
* :func:`numbits_any_intersection`
* :func:`num_in_numbits`
* :func:`numbits_to_nums`
`connection` is a :class:`sqlite3.Connection `
object. After creating the connection, pass it to this function to
register the numbits functions. Then you can use numbits functions in your
queries::
import sqlite3
from coverage.numbits import register_sqlite_functions
conn = sqlite3.connect("example.db")
register_sqlite_functions(conn)
c = conn.cursor()
# Kind of a nonsense query:
# Find all the files and contexts that executed line 47 in any file:
c.execute(
"select file_id, context_id from line_bits where num_in_numbits(?, numbits)",
(47,)
)
"""
connection.create_function("numbits_union", 2, numbits_union)
connection.create_function("numbits_intersection", 2, numbits_intersection)
connection.create_function("numbits_any_intersection", 2, numbits_any_intersection)
connection.create_function("num_in_numbits", 2, num_in_numbits)
connection.create_function("numbits_to_nums", 1, lambda b: json.dumps(numbits_to_nums(b)))
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/parser.py 0000644 0001751 0001751 00000132222 15073731535 016515 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Code parsing for coverage.py."""
from __future__ import annotations
import ast
import collections
import functools
import os
import re
import token
import tokenize
from collections.abc import Iterable, Sequence
from dataclasses import dataclass
from types import CodeType
from typing import Callable, Optional, Protocol, cast
from coverage import env
from coverage.bytecode import code_objects
from coverage.debug import short_stack
from coverage.exceptions import NoSource, NotPython
from coverage.misc import isolate_module, nice_pair
from coverage.phystokens import generate_tokens
from coverage.types import TArc, TLineNo
os = isolate_module(os)
class PythonParser:
"""Parse code to find executable lines, excluded lines, etc.
This information is all based on static analysis: no code execution is
involved.
"""
def __init__(
self,
text: str | None = None,
filename: str | None = None,
exclude: str | None = None,
) -> None:
"""
Source can be provided as `text`, the text itself, or `filename`, from
which the text will be read. Excluded lines are those that match
`exclude`, a regex string.
"""
assert text or filename, "PythonParser needs either text or filename"
self.filename = filename or ""
if text is not None:
self.text: str = text
else:
from coverage.python import get_python_source
try:
self.text = get_python_source(self.filename)
except OSError as err:
raise NoSource(f"No source for code: '{self.filename}': {err}") from err
self.exclude = exclude
# The parsed AST of the text.
self._ast_root: ast.AST | None = None
# The normalized line numbers of the statements in the code. Exclusions
# are taken into account, and statements are adjusted to their first
# lines.
self.statements: set[TLineNo] = set()
# The normalized line numbers of the excluded lines in the code,
# adjusted to their first lines.
self.excluded: set[TLineNo] = set()
# The raw_* attributes are only used in this class, and in
# lab/parser.py to show how this class is working.
# The line numbers that start statements, as reported by the line
# number table in the bytecode.
self.raw_statements: set[TLineNo] = set()
# The raw line numbers of excluded lines of code, as marked by pragmas.
self.raw_excluded: set[TLineNo] = set()
# The line numbers of docstring lines.
self.raw_docstrings: set[TLineNo] = set()
# Internal detail, used by lab/parser.py.
self.show_tokens = False
# A dict mapping line numbers to lexical statement starts for
# multi-line statements.
self._multiline: dict[TLineNo, TLineNo] = {}
# Lazily-created arc data, and missing arc descriptions.
self._all_arcs: set[TArc] | None = None
self._missing_arc_fragments: TArcFragments | None = None
self._with_jump_fixers: dict[TArc, tuple[TArc, TArc]] = {}
def lines_matching(self, regex: str) -> set[TLineNo]:
"""Find the lines matching a regex.
Returns a set of line numbers, the lines that contain a match for
`regex`. The entire line needn't match, just a part of it.
Handles multiline regex patterns.
"""
matches: set[TLineNo] = set()
last_start = 0
last_start_line = 0
for match in re.finditer(regex, self.text, flags=re.MULTILINE):
start, end = match.span()
start_line = last_start_line + self.text.count("\n", last_start, start)
end_line = last_start_line + self.text.count("\n", last_start, end)
matches.update(self._multiline.get(i, i) for i in range(start_line + 1, end_line + 2))
last_start = start
last_start_line = start_line
return matches
def _raw_parse(self) -> None:
"""Parse the source to find the interesting facts about its lines.
A handful of attributes are updated.
"""
# Find lines which match an exclusion pattern.
if self.exclude:
self.raw_excluded = self.lines_matching(self.exclude)
self.excluded = set(self.raw_excluded)
# The current number of indents.
indent: int = 0
# An exclusion comment will exclude an entire clause at this indent.
exclude_indent: int = 0
# Are we currently excluding lines?
excluding: bool = False
# The line number of the first line in a multi-line statement.
first_line: int = 0
# Is the file empty?
empty: bool = True
# Parenthesis (and bracket) nesting level.
nesting: int = 0
assert self.text is not None
tokgen = generate_tokens(self.text)
for toktype, ttext, (slineno, _), (elineno, _), ltext in tokgen:
if self.show_tokens: # pragma: debugging
print(
"%10s %5s %-20r %r"
% (
tokenize.tok_name.get(toktype, toktype),
nice_pair((slineno, elineno)),
ttext,
ltext,
)
)
if toktype == token.INDENT:
indent += 1
elif toktype == token.DEDENT:
indent -= 1
elif toktype == token.OP:
if ttext == ":" and nesting == 0:
should_exclude = self.excluded.intersection(range(first_line, elineno + 1))
if not excluding and should_exclude:
# Start excluding a suite. We trigger off of the colon
# token so that the #pragma comment will be recognized on
# the same line as the colon.
self.excluded.add(elineno)
exclude_indent = indent
excluding = True
elif ttext in "([{":
nesting += 1
elif ttext in ")]}":
nesting -= 1
elif toktype == token.NEWLINE:
if first_line and elineno != first_line:
# We're at the end of a line, and we've ended on a
# different line than the first line of the statement,
# so record a multi-line range.
for l in range(first_line, elineno + 1):
self._multiline[l] = first_line
first_line = 0
if ttext.strip() and toktype != tokenize.COMMENT:
# A non-white-space token.
empty = False
if not first_line:
# The token is not white space, and is the first in a statement.
first_line = slineno
# Check whether to end an excluded suite.
if excluding and indent <= exclude_indent:
excluding = False
if excluding:
self.excluded.add(elineno)
# Find the starts of the executable statements.
if not empty:
byte_parser = ByteParser(self.text, filename=self.filename)
self.raw_statements.update(byte_parser._find_statements())
self.excluded = self.first_lines(self.excluded)
# AST lets us find classes, docstrings, and decorator-affected
# functions and classes.
assert self._ast_root is not None
for node in ast.walk(self._ast_root):
# Find docstrings.
if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef, ast.Module)):
if node.body:
first = node.body[0]
if (
isinstance(first, ast.Expr)
and isinstance(first.value, ast.Constant)
and isinstance(first.value.value, str)
):
self.raw_docstrings.update(
range(first.lineno, cast(int, first.end_lineno) + 1)
)
# Exclusions carry from decorators and signatures to the bodies of
# functions and classes.
if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
first_line = min((d.lineno for d in node.decorator_list), default=node.lineno)
if self.excluded.intersection(range(first_line, node.lineno + 1)):
self.excluded.update(range(first_line, cast(int, node.end_lineno) + 1))
@functools.lru_cache(maxsize=1000)
def first_line(self, lineno: TLineNo) -> TLineNo:
"""Return the first line number of the statement including `lineno`."""
if lineno < 0:
lineno = -self._multiline.get(-lineno, -lineno)
else:
lineno = self._multiline.get(lineno, lineno)
return lineno
def first_lines(self, linenos: Iterable[TLineNo]) -> set[TLineNo]:
"""Map the line numbers in `linenos` to the correct first line of the
statement.
Returns a set of the first lines.
"""
return {self.first_line(l) for l in linenos}
def translate_lines(self, lines: Iterable[TLineNo]) -> set[TLineNo]:
"""Implement `FileReporter.translate_lines`."""
return self.first_lines(lines)
def translate_arcs(self, arcs: Iterable[TArc]) -> set[TArc]:
"""Implement `FileReporter.translate_arcs`."""
return {(self.first_line(a), self.first_line(b)) for (a, b) in self.fix_with_jumps(arcs)}
def parse_source(self) -> None:
"""Parse source text to find executable lines, excluded lines, etc.
Sets the .excluded and .statements attributes, normalized to the first
line of multi-line statements.
"""
try:
self._ast_root = ast.parse(self.text)
self._raw_parse()
except (tokenize.TokenError, IndentationError, SyntaxError) as err:
if hasattr(err, "lineno"):
lineno = err.lineno # IndentationError
else:
lineno = err.args[1][0] # TokenError
raise NotPython(
f"Couldn't parse '{self.filename}' as Python source: "
+ f"{err.args[0]!r} at line {lineno}",
) from err
ignore = self.excluded | self.raw_docstrings
starts = self.raw_statements - ignore
self.statements = self.first_lines(starts) - ignore
def arcs(self) -> set[TArc]:
"""Get information about the arcs available in the code.
Returns a set of line number pairs. Line numbers have been normalized
to the first line of multi-line statements.
"""
if self._all_arcs is None:
self._analyze_ast()
assert self._all_arcs is not None
return self._all_arcs
def _analyze_ast(self) -> None:
"""Run the AstArcAnalyzer and save its results.
`_all_arcs` is the set of arcs in the code.
"""
assert self._ast_root is not None
aaa = AstArcAnalyzer(self.filename, self._ast_root, self.raw_statements, self._multiline)
aaa.analyze()
arcs = aaa.arcs
self._with_jump_fixers = aaa.with_jump_fixers()
if self._with_jump_fixers:
arcs = self.fix_with_jumps(arcs)
self._all_arcs = set()
for l1, l2 in arcs:
fl1 = self.first_line(l1)
fl2 = self.first_line(l2)
if fl1 != fl2:
self._all_arcs.add((fl1, fl2))
self._missing_arc_fragments = aaa.missing_arc_fragments
def fix_with_jumps(self, arcs: Iterable[TArc]) -> set[TArc]:
"""Adjust arcs to fix jumps leaving `with` statements.
Consider this code:
with open("/tmp/test", "w") as f1:
a = 2
b = 3
print(4)
In 3.10+, we get traces for lines 1, 2, 3, 1, 4. But we want to present
it to the user as if it had been 1, 2, 3, 4. The arc 3->1 should be
replaced with 3->4, and 1->4 should be removed.
For this code, the fixers dict is {(3, 1): ((1, 4), (3, 4))}. The key
is the actual measured arc from the end of the with block back to the
start of the with-statement. The values are start_next (the with
statement to the next statement after the with), and end_next (the end
of the with-statement to the next statement after the with).
With nested with-statements, we have to trace through a few levels to
correct a longer chain of arcs.
"""
to_remove = set()
to_add = set()
for arc in arcs:
if arc in self._with_jump_fixers:
end0 = arc[0]
to_remove.add(arc)
start_next, end_next = self._with_jump_fixers[arc]
while start_next in self._with_jump_fixers:
to_remove.add(start_next)
start_next, end_next = self._with_jump_fixers[start_next]
to_remove.add(end_next)
to_add.add((end0, end_next[1]))
to_remove.add(start_next)
arcs = (set(arcs) | to_add) - to_remove
return arcs
@functools.lru_cache
def exit_counts(self) -> dict[TLineNo, int]:
"""Get a count of exits from that each line.
Excluded lines are excluded.
"""
exit_counts: dict[TLineNo, int] = collections.defaultdict(int)
for l1, l2 in self.arcs():
assert l1 > 0, f"{l1=} should be greater than zero in {self.filename}"
if l1 in self.excluded:
# Don't report excluded lines as line numbers.
continue
if l2 in self.excluded:
# Arcs to excluded lines shouldn't count.
continue
exit_counts[l1] += 1
return exit_counts
def _finish_action_msg(self, action_msg: str | None, end: TLineNo) -> str:
"""Apply some defaulting and formatting to an arc's description."""
if action_msg is None:
if end < 0:
action_msg = "jump to the function exit"
else:
action_msg = "jump to line {lineno}"
action_msg = action_msg.format(lineno=end)
return action_msg
def missing_arc_description(self, start: TLineNo, end: TLineNo) -> str:
"""Provide an English sentence describing a missing arc."""
if self._missing_arc_fragments is None:
self._analyze_ast()
assert self._missing_arc_fragments is not None
fragment_pairs = self._missing_arc_fragments.get((start, end), [(None, None)])
msgs = []
for missing_cause_msg, action_msg in fragment_pairs:
action_msg = self._finish_action_msg(action_msg, end)
msg = f"line {start} didn't {action_msg}"
if missing_cause_msg is not None:
msg += f" because {missing_cause_msg.format(lineno=start)}"
msgs.append(msg)
return " or ".join(msgs)
def arc_description(self, start: TLineNo, end: TLineNo) -> str:
"""Provide an English description of an arc's effect."""
if self._missing_arc_fragments is None:
self._analyze_ast()
assert self._missing_arc_fragments is not None
fragment_pairs = self._missing_arc_fragments.get((start, end), [(None, None)])
action_msg = self._finish_action_msg(fragment_pairs[0][1], end)
return action_msg
class ByteParser:
"""Parse bytecode to understand the structure of code."""
def __init__(
self,
text: str,
code: CodeType | None = None,
filename: str | None = None,
) -> None:
self.text = text
if code is not None:
self.code = code
else:
assert filename is not None
# We only get here if earlier ast parsing succeeded, so no need to
# catch errors.
self.code = compile(text, filename, "exec", dont_inherit=True)
def child_parsers(self) -> Iterable[ByteParser]:
"""Iterate over all the code objects nested within this one.
The iteration includes `self` as its first value.
We skip code objects named `__annotate__` since they are deferred
annotations that usually are never run. If there are errors in the
annotations, they will be caught by type checkers or other tools that
use annotations.
"""
return (
ByteParser(self.text, code=c)
for c in code_objects(self.code)
if c.co_name != "__annotate__"
)
def _line_numbers(self) -> Iterable[TLineNo]:
"""Yield the line numbers possible in this code object.
Uses co_lines() to produce a sequence: l0, l1, ...
"""
for _, _, line in self.code.co_lines():
if line:
yield line
def _find_statements(self) -> Iterable[TLineNo]:
"""Find the statements in `self.code`.
Produce a sequence of line numbers that start statements. Recurses
into all code objects reachable from `self.code`.
"""
for bp in self.child_parsers():
# Get all of the lineno information from this code.
yield from bp._line_numbers()
#
# AST analysis
#
@dataclass(frozen=True, order=True)
class ArcStart:
"""The information needed to start an arc.
`lineno` is the line number the arc starts from.
`cause` is an English text fragment used as the `missing_cause_msg` for
AstArcAnalyzer.missing_arc_fragments. It will be used to describe why an
arc wasn't executed, so should fit well into a sentence of the form,
"Line 17 didn't run because {cause}." The fragment can include "{lineno}"
to have `lineno` interpolated into it.
As an example, this code::
if something(x): # line 1
func(x) # line 2
more_stuff() # line 3
would have two ArcStarts:
- ArcStart(1, "the condition on line 1 was always true")
- ArcStart(1, "the condition on line 1 was never true")
The first would be used to create an arc from 1 to 3, creating a message like
"line 1 didn't jump to line 3 because the condition on line 1 was always true."
The second would be used for the arc from 1 to 2, creating a message like
"line 1 didn't jump to line 2 because the condition on line 1 was never true."
"""
lineno: TLineNo
cause: str = ""
class TAddArcFn(Protocol):
"""The type for AstArcAnalyzer.add_arc()."""
def __call__(
self,
start: TLineNo,
end: TLineNo,
missing_cause_msg: str | None = None,
action_msg: str | None = None,
) -> None:
"""
Record an arc from `start` to `end`.
`missing_cause_msg` is a description of the reason the arc wasn't
taken if it wasn't taken. For example, "the condition on line 10 was
never true."
`action_msg` is a description of what the arc does, like "jump to line
10" or "exit from function 'fooey'."
"""
TArcFragments = dict[TArc, list[tuple[Optional[str], Optional[str]]]]
class Block:
"""
Blocks need to handle various exiting statements in their own ways.
All of these methods take a list of exits, and a callable `add_arc`
function that they can use to add arcs if needed. They return True if the
exits are handled, or False if the search should continue up the block
stack.
"""
# pylint: disable=unused-argument
def process_break_exits(self, exits: set[ArcStart], add_arc: TAddArcFn) -> bool:
"""Process break exits."""
return False
def process_continue_exits(self, exits: set[ArcStart], add_arc: TAddArcFn) -> bool:
"""Process continue exits."""
return False
def process_raise_exits(self, exits: set[ArcStart], add_arc: TAddArcFn) -> bool:
"""Process raise exits."""
return False
def process_return_exits(self, exits: set[ArcStart], add_arc: TAddArcFn) -> bool:
"""Process return exits."""
return False
class LoopBlock(Block):
"""A block on the block stack representing a `for` or `while` loop."""
def __init__(self, start: TLineNo) -> None:
# The line number where the loop starts.
self.start = start
# A set of ArcStarts, the arcs from break statements exiting this loop.
self.break_exits: set[ArcStart] = set()
def process_break_exits(self, exits: set[ArcStart], add_arc: TAddArcFn) -> bool:
self.break_exits.update(exits)
return True
def process_continue_exits(self, exits: set[ArcStart], add_arc: TAddArcFn) -> bool:
for xit in exits:
add_arc(xit.lineno, self.start, xit.cause)
return True
class FunctionBlock(Block):
"""A block on the block stack representing a function definition."""
def __init__(self, start: TLineNo, name: str) -> None:
# The line number where the function starts.
self.start = start
# The name of the function.
self.name = name
def process_raise_exits(self, exits: set[ArcStart], add_arc: TAddArcFn) -> bool:
for xit in exits:
add_arc(
xit.lineno,
-self.start,
xit.cause,
f"except from function {self.name!r}",
)
return True
def process_return_exits(self, exits: set[ArcStart], add_arc: TAddArcFn) -> bool:
for xit in exits:
add_arc(
xit.lineno,
-self.start,
xit.cause,
f"return from function {self.name!r}",
)
return True
class TryBlock(Block):
"""A block on the block stack representing a `try` block."""
def __init__(self, handler_start: TLineNo | None, final_start: TLineNo | None) -> None:
# The line number of the first "except" handler, if any.
self.handler_start = handler_start
# The line number of the "finally:" clause, if any.
self.final_start = final_start
def process_raise_exits(self, exits: set[ArcStart], add_arc: TAddArcFn) -> bool:
if self.handler_start is not None:
for xit in exits:
add_arc(xit.lineno, self.handler_start, xit.cause)
return True
# TODO: Shouldn't the cause messages join with "and" instead of "or"?
def is_constant_test_expr(node: ast.AST) -> tuple[bool, bool]:
"""Is this a compile-time constant test expression?
We don't try to mimic all of CPython's optimizations. We just have to
handle the kinds of constant expressions people might actually use.
"""
match node:
case ast.Constant():
return True, bool(node.value)
case ast.Name():
if node.id in ["True", "False", "None", "__debug__"]:
return True, eval(node.id) # pylint: disable=eval-used
case ast.UnaryOp():
if isinstance(node.op, ast.Not):
is_constant, val = is_constant_test_expr(node.operand)
return is_constant, not val
case ast.BoolOp():
rets = [is_constant_test_expr(v) for v in node.values]
is_constant = all(is_const for is_const, _ in rets)
if is_constant:
op = any if isinstance(node.op, ast.Or) else all
return True, op(v for _, v in rets)
return False, False
class AstArcAnalyzer:
"""Analyze source text with an AST to find executable code paths.
The .analyze() method does the work, and populates these attributes:
`arcs`: a set of (from, to) pairs of the the arcs possible in the code.
`missing_arc_fragments`: a dict mapping (from, to) arcs to lists of
message fragments explaining why the arc is missing from execution::
{ (start, end): [(missing_cause_msg, action_msg), ...], }
For an arc starting from line 17, they should be usable to form complete
sentences like: "Line 17 didn't {action_msg} because {missing_cause_msg}".
NOTE: Starting in July 2024, I've been whittling this down to only report
arc that are part of true branches. It's not clear how far this work will
go.
"""
def __init__(
self,
filename: str,
root_node: ast.AST,
statements: set[TLineNo],
multiline: dict[TLineNo, TLineNo],
) -> None:
self.filename = filename
self.root_node = root_node
self.statements = {multiline.get(l, l) for l in statements}
self.multiline = multiline
# Turn on AST dumps with an environment variable.
# $set_env.py: COVERAGE_AST_DUMP - Dump the AST nodes when parsing code.
dump_ast = bool(int(os.getenv("COVERAGE_AST_DUMP", "0")))
if dump_ast: # pragma: debugging
# Dump the AST so that failing tests have helpful output.
print(f"Statements: {self.statements}")
print(f"Multiline map: {self.multiline}")
print(ast.dump(self.root_node, include_attributes=True, indent=4))
self.arcs: set[TArc] = set()
self.missing_arc_fragments: TArcFragments = collections.defaultdict(list)
self.block_stack: list[Block] = []
# If `with` clauses jump to their start on the way out, we need
# information to be able to skip over that jump. We record the arcs
# from `with` into the clause (with_entries), and the arcs from the
# clause to the `with` (with_exits).
self.current_with_starts: set[TLineNo] = set()
self.all_with_starts: set[TLineNo] = set()
self.with_entries: set[TArc] = set()
self.with_exits: set[TArc] = set()
# $set_env.py: COVERAGE_TRACK_ARCS - Trace possible arcs added while parsing code.
self.debug = bool(int(os.getenv("COVERAGE_TRACK_ARCS", "0")))
def analyze(self) -> None:
"""Examine the AST tree from `self.root_node` to determine possible arcs."""
for node in ast.walk(self.root_node):
node_name = node.__class__.__name__
code_object_handler = getattr(self, f"_code_object__{node_name}", None)
if code_object_handler is not None:
code_object_handler(node)
def with_jump_fixers(self) -> dict[TArc, tuple[TArc, TArc]]:
"""Get a dict with data for fixing jumps out of with statements.
Returns a dict. The keys are arcs leaving a with-statement by jumping
back to its start. The values are pairs: first, the arc from the start
to the next statement, then the arc that exits the with without going
to the start.
"""
fixers = {}
with_nexts = {
arc
for arc in self.arcs
if arc[0] in self.all_with_starts and arc not in self.with_entries
}
for start in self.all_with_starts:
nexts = {arc[1] for arc in with_nexts if arc[0] == start}
if not nexts:
continue
assert len(nexts) == 1, f"Expected one arc, got {nexts} with {start = }"
nxt = nexts.pop()
ends = {arc[0] for arc in self.with_exits if arc[1] == start}
for end in ends:
fixers[(end, start)] = ((start, nxt), (end, nxt))
return fixers
# Code object dispatchers: _code_object__*
#
# These methods are used by analyze() as the start of the analysis.
# There is one for each construct with a code object.
def _code_object__Module(self, node: ast.Module) -> None:
start = self.line_for_node(node)
if node.body:
exits = self.process_body(node.body)
for xit in exits:
self.add_arc(xit.lineno, -start, xit.cause, "exit the module")
else:
# Empty module.
self.add_arc(start, -start)
def _code_object__FunctionDef(self, node: ast.FunctionDef) -> None:
start = self.line_for_node(node)
self.block_stack.append(FunctionBlock(start=start, name=node.name))
exits = self.process_body(node.body)
self.process_return_exits(exits)
self.block_stack.pop()
_code_object__AsyncFunctionDef = _code_object__FunctionDef
def _code_object__ClassDef(self, node: ast.ClassDef) -> None:
start = self.line_for_node(node)
exits = self.process_body(node.body)
for xit in exits:
self.add_arc(xit.lineno, -start, xit.cause, f"exit class {node.name!r}")
def add_arc(
self,
start: TLineNo,
end: TLineNo,
missing_cause_msg: str | None = None,
action_msg: str | None = None,
) -> None:
"""Add an arc, including message fragments to use if it is missing."""
if self.debug: # pragma: debugging
print(f"Adding possible arc: ({start}, {end}): {missing_cause_msg!r}, {action_msg!r}")
print(short_stack(), end="\n\n")
self.arcs.add((start, end))
if start in self.current_with_starts:
self.with_entries.add((start, end))
if missing_cause_msg is not None or action_msg is not None:
self.missing_arc_fragments[(start, end)].append((missing_cause_msg, action_msg))
def nearest_blocks(self) -> Iterable[Block]:
"""Yield the blocks in nearest-to-farthest order."""
return reversed(self.block_stack)
def line_for_node(self, node: ast.AST) -> TLineNo:
"""What is the right line number to use for this node?
This dispatches to _line__Node functions where needed.
"""
node_name = node.__class__.__name__
handler = cast(
Optional[Callable[[ast.AST], TLineNo]],
getattr(self, f"_line__{node_name}", None),
)
if handler is not None:
line = handler(node)
else:
line = node.lineno # type: ignore[attr-defined]
return self.multiline.get(line, line)
# First lines: _line__*
#
# Dispatched by line_for_node, each method knows how to identify the first
# line number in the node, as Python will report it.
def _line_decorated(self, node: ast.FunctionDef) -> TLineNo:
"""Compute first line number for things that can be decorated (classes and functions)."""
if node.decorator_list:
lineno = node.decorator_list[0].lineno
else:
lineno = node.lineno
return lineno
def _line__Assign(self, node: ast.Assign) -> TLineNo:
return self.line_for_node(node.value)
_line__ClassDef = _line_decorated
def _line__Dict(self, node: ast.Dict) -> TLineNo:
if node.keys:
if node.keys[0] is not None:
return node.keys[0].lineno
else:
# Unpacked dict literals `{**{"a":1}}` have None as the key,
# use the value in that case.
return node.values[0].lineno
else:
return node.lineno
_line__FunctionDef = _line_decorated
_line__AsyncFunctionDef = _line_decorated
def _line__List(self, node: ast.List) -> TLineNo:
if node.elts:
return self.line_for_node(node.elts[0])
else:
return node.lineno
def _line__Module(self, node: ast.Module) -> TLineNo: # pylint: disable=unused-argument
return 1
# The node types that just flow to the next node with no complications.
OK_TO_DEFAULT = {
"AnnAssign",
"Assign",
"Assert",
"AugAssign",
"Delete",
"Expr",
"Global",
"Import",
"ImportFrom",
"Nonlocal",
"Pass",
}
def node_exits(self, node: ast.AST) -> set[ArcStart]:
"""Find the set of arc starts that exit this node.
Return a set of ArcStarts, exits from this node to the next. Because a
node represents an entire sub-tree (including its children), the exits
from a node can be arbitrarily complex::
if something(1):
if other(2):
doit(3)
else:
doit(5)
There are three exits from line 1: they start at lines 1, 3 and 5.
There are two exits from line 2: lines 3 and 5.
"""
node_name = node.__class__.__name__
handler = cast(
Optional[Callable[[ast.AST], set[ArcStart]]],
getattr(self, f"_handle__{node_name}", None),
)
if handler is not None:
arc_starts = handler(node)
else:
# No handler: either it's something that's ok to default (a simple
# statement), or it's something we overlooked.
if env.TESTING:
if node_name not in self.OK_TO_DEFAULT:
raise RuntimeError(f"*** Unhandled: {node}") # pragma: only failure
# Default for simple statements: one exit from this node.
arc_starts = {ArcStart(self.line_for_node(node))}
return arc_starts
def process_body(
self,
body: Sequence[ast.AST],
from_start: ArcStart | None = None,
prev_starts: set[ArcStart] | None = None,
) -> set[ArcStart]:
"""Process the body of a compound statement.
`body` is the body node to process.
`from_start` is a single `ArcStart` that starts an arc into this body.
`prev_starts` is a set of ArcStarts that can all be the start of arcs
into this body. Only one of `from_start` and `prev_starts` should be
given.
Records arcs within the body by calling `self.add_arc`.
Returns a set of ArcStarts, the exits from this body.
"""
if prev_starts is None:
if from_start is None:
prev_starts = set()
else:
prev_starts = {from_start}
else:
assert from_start is None
# Loop over the nodes in the body, making arcs from each one's exits to
# the next node.
for body_node in body:
lineno = self.line_for_node(body_node)
if lineno not in self.statements:
continue
for prev_start in prev_starts:
self.add_arc(prev_start.lineno, lineno, prev_start.cause)
prev_starts = self.node_exits(body_node)
return prev_starts
# Exit processing: process_*_exits
#
# These functions process the four kinds of jump exits: break, continue,
# raise, and return. To figure out where an exit goes, we have to look at
# the block stack context. For example, a break will jump to the nearest
# enclosing loop block, or the nearest enclosing finally block, whichever
# is nearer.
def process_break_exits(self, exits: set[ArcStart]) -> None:
"""Add arcs due to jumps from `exits` being breaks."""
for block in self.nearest_blocks(): # pragma: always breaks
if block.process_break_exits(exits, self.add_arc):
break
def process_continue_exits(self, exits: set[ArcStart]) -> None:
"""Add arcs due to jumps from `exits` being continues."""
for block in self.nearest_blocks(): # pragma: always breaks
if block.process_continue_exits(exits, self.add_arc):
break
def process_raise_exits(self, exits: set[ArcStart]) -> None:
"""Add arcs due to jumps from `exits` being raises."""
for block in self.nearest_blocks():
if block.process_raise_exits(exits, self.add_arc):
break
def process_return_exits(self, exits: set[ArcStart]) -> None:
"""Add arcs due to jumps from `exits` being returns."""
for block in self.nearest_blocks(): # pragma: always breaks
if block.process_return_exits(exits, self.add_arc):
break
# Node handlers: _handle__*
#
# Each handler deals with a specific AST node type, dispatched from
# node_exits. Handlers return the set of exits from that node, and can
# also call self.add_arc to record arcs they find. These functions mirror
# the Python semantics of each syntactic construct. See the docstring
# for node_exits to understand the concept of exits from a node.
#
# Every node type that represents a statement should have a handler, or it
# should be listed in OK_TO_DEFAULT.
def _handle__Break(self, node: ast.Break) -> set[ArcStart]:
here = self.line_for_node(node)
break_start = ArcStart(here, cause="the break on line {lineno} wasn't executed")
self.process_break_exits({break_start})
return set()
def _handle_decorated(self, node: ast.FunctionDef) -> set[ArcStart]:
"""Add arcs for things that can be decorated (classes and functions)."""
main_line: TLineNo = node.lineno
last: TLineNo | None = node.lineno
decs = node.decorator_list
if decs:
last = None
for dec_node in decs:
dec_start = self.line_for_node(dec_node)
if last is not None and dec_start != last:
self.add_arc(last, dec_start)
last = dec_start
assert last is not None
self.add_arc(last, main_line)
last = main_line
# The definition line may have been missed, but we should have it
# in `self.statements`. For some constructs, `line_for_node` is
# not what we'd think of as the first line in the statement, so map
# it to the first one.
assert node.body, f"Oops: {node.body = } in {self.filename}@{node.lineno}"
# The body is handled in collect_arcs.
assert last is not None
return {ArcStart(last)}
_handle__ClassDef = _handle_decorated
def _handle__Continue(self, node: ast.Continue) -> set[ArcStart]:
here = self.line_for_node(node)
continue_start = ArcStart(here, cause="the continue on line {lineno} wasn't executed")
self.process_continue_exits({continue_start})
return set()
def _handle__For(self, node: ast.For) -> set[ArcStart]:
start = self.line_for_node(node.iter)
self.block_stack.append(LoopBlock(start=start))
from_start = ArcStart(start, cause="the loop on line {lineno} never started")
exits = self.process_body(node.body, from_start=from_start)
# Any exit from the body will go back to the top of the loop.
for xit in exits:
self.add_arc(xit.lineno, start, xit.cause)
my_block = self.block_stack.pop()
assert isinstance(my_block, LoopBlock)
exits = my_block.break_exits
from_start = ArcStart(start, cause="the loop on line {lineno} didn't complete")
if node.orelse:
else_exits = self.process_body(node.orelse, from_start=from_start)
exits |= else_exits
else:
# No else clause: exit from the for line.
exits.add(from_start)
return exits
_handle__AsyncFor = _handle__For
_handle__FunctionDef = _handle_decorated
_handle__AsyncFunctionDef = _handle_decorated
def _handle__If(self, node: ast.If) -> set[ArcStart]:
start = self.line_for_node(node.test)
constant_test, val = is_constant_test_expr(node.test)
exits = set()
if not constant_test or val:
from_start = ArcStart(start, cause="the condition on line {lineno} was never true")
exits |= self.process_body(node.body, from_start=from_start)
if not constant_test or not val:
from_start = ArcStart(start, cause="the condition on line {lineno} was always true")
exits |= self.process_body(node.orelse, from_start=from_start)
return exits
def _handle__Match(self, node: ast.Match) -> set[ArcStart]:
start = self.line_for_node(node)
last_start = start
exits = set()
for case in node.cases:
case_start = self.line_for_node(case.pattern)
self.add_arc(last_start, case_start, "the pattern on line {lineno} always matched")
from_start = ArcStart(
case_start,
cause="the pattern on line {lineno} never matched",
)
exits |= self.process_body(case.body, from_start=from_start)
last_start = case_start
# case is now the last case, check for wildcard match.
pattern = case.pattern # pylint: disable=undefined-loop-variable
while isinstance(pattern, ast.MatchOr):
pattern = pattern.patterns[-1]
while isinstance(pattern, ast.MatchAs) and pattern.pattern is not None:
pattern = pattern.pattern
had_wildcard = (
isinstance(pattern, ast.MatchAs) and pattern.pattern is None and case.guard is None # pylint: disable=undefined-loop-variable
)
if not had_wildcard:
exits.add(
ArcStart(case_start, cause="the pattern on line {lineno} always matched"),
)
return exits
def _handle__Raise(self, node: ast.Raise) -> set[ArcStart]:
here = self.line_for_node(node)
raise_start = ArcStart(here, cause="the raise on line {lineno} wasn't executed")
self.process_raise_exits({raise_start})
# `raise` statement jumps away, no exits from here.
return set()
def _handle__Return(self, node: ast.Return) -> set[ArcStart]:
here = self.line_for_node(node)
return_start = ArcStart(here, cause="the return on line {lineno} wasn't executed")
self.process_return_exits({return_start})
# `return` statement jumps away, no exits from here.
return set()
def _handle__Try(self, node: ast.Try) -> set[ArcStart]:
if node.handlers:
handler_start = self.line_for_node(node.handlers[0])
else:
handler_start = None
if node.finalbody:
final_start = self.line_for_node(node.finalbody[0])
else:
final_start = None
# This is true by virtue of Python syntax: have to have either except
# or finally, or both.
assert handler_start is not None or final_start is not None
try_block = TryBlock(handler_start, final_start)
self.block_stack.append(try_block)
start = self.line_for_node(node)
exits = self.process_body(node.body, from_start=ArcStart(start))
# We're done with the `try` body, so this block no longer handles
# exceptions. We keep the block so the `finally` clause can pick up
# flows from the handlers and `else` clause.
if node.finalbody:
try_block.handler_start = None
else:
self.block_stack.pop()
handler_exits: set[ArcStart] = set()
if node.handlers:
for handler_node in node.handlers:
handler_start = self.line_for_node(handler_node)
from_cause = "the exception caught by line {lineno} didn't happen"
from_start = ArcStart(handler_start, cause=from_cause)
handler_exits |= self.process_body(handler_node.body, from_start=from_start)
if node.orelse:
exits = self.process_body(node.orelse, prev_starts=exits)
exits |= handler_exits
if node.finalbody:
self.block_stack.pop()
final_from = exits
final_exits = self.process_body(node.finalbody, prev_starts=final_from)
if exits:
# The finally clause's exits are only exits for the try block
# as a whole if the try block had some exits to begin with.
exits = final_exits
return exits
def _handle__While(self, node: ast.While) -> set[ArcStart]:
start = to_top = self.line_for_node(node.test)
constant_test, _ = is_constant_test_expr(node.test)
self.block_stack.append(LoopBlock(start=to_top))
from_start = ArcStart(start, cause="the condition on line {lineno} was never true")
exits = self.process_body(node.body, from_start=from_start)
for xit in exits:
self.add_arc(xit.lineno, to_top, xit.cause)
exits = set()
my_block = self.block_stack.pop()
assert isinstance(my_block, LoopBlock)
exits.update(my_block.break_exits)
from_start = ArcStart(start, cause="the condition on line {lineno} was always true")
if node.orelse:
else_exits = self.process_body(node.orelse, from_start=from_start)
exits |= else_exits
else:
# No `else` clause: you can exit from the start.
if not constant_test:
exits.add(from_start)
return exits
def _handle__With(self, node: ast.With) -> set[ArcStart]:
if env.PYBEHAVIOR.exit_with_through_ctxmgr:
starts = [self.line_for_node(item.context_expr) for item in node.items]
else:
starts = [self.line_for_node(node)]
for start in starts:
self.current_with_starts.add(start)
self.all_with_starts.add(start)
exits = self.process_body(node.body, from_start=ArcStart(starts[-1]))
start = starts[-1]
self.current_with_starts.remove(start)
with_exit = {ArcStart(start)}
if exits:
for xit in exits:
self.add_arc(xit.lineno, start)
self.with_exits.add((xit.lineno, start))
exits = with_exit
return exits
_handle__AsyncWith = _handle__With
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/patch.py 0000644 0001751 0001751 00000012675 15073731535 016331 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Invasive patches for coverage.py."""
from __future__ import annotations
import atexit
import contextlib
import os
import site
from pathlib import Path
from typing import TYPE_CHECKING, Any, NoReturn
from coverage import env
from coverage.debug import NoDebugging, DevNullDebug
from coverage.exceptions import ConfigError, CoverageException
if TYPE_CHECKING:
from coverage import Coverage
from coverage.config import CoverageConfig
from coverage.types import TDebugCtl
def apply_patches(
cov: Coverage,
config: CoverageConfig,
debug: TDebugCtl,
*,
make_pth_file: bool = True,
) -> None:
"""Apply invasive patches requested by `[run] patch=`."""
debug = debug if debug.should("patch") else DevNullDebug()
for patch in sorted(set(config.patch)):
match patch:
case "_exit":
_patch__exit(cov, debug)
case "execv":
_patch_execv(cov, config, debug)
case "fork":
_patch_fork(debug)
case "subprocess":
_patch_subprocess(config, debug, make_pth_file)
case _:
raise ConfigError(f"Unknown patch {patch!r}")
def _patch__exit(cov: Coverage, debug: TDebugCtl) -> None:
"""Patch os._exit."""
debug.write("Patching _exit")
old_exit = os._exit
def coverage_os_exit_patch(status: int) -> NoReturn:
with contextlib.suppress(Exception):
debug.write(f"Using _exit patch with {cov = }")
with contextlib.suppress(Exception):
cov.save()
old_exit(status)
os._exit = coverage_os_exit_patch
def _patch_execv(cov: Coverage, config: CoverageConfig, debug: TDebugCtl) -> None:
"""Patch the execv family of functions."""
if env.WINDOWS:
raise CoverageException("patch=execv isn't supported yet on Windows.")
debug.write("Patching execv")
def make_execv_patch(fname: str, old_execv: Any) -> Any:
def coverage_execv_patch(*args: Any, **kwargs: Any) -> Any:
with contextlib.suppress(Exception):
debug.write(f"Using execv patch for {fname} with {cov = }")
with contextlib.suppress(Exception):
cov.save()
if fname.endswith("e"):
# Assume the `env` argument is passed positionally.
new_env = args[-1]
# Pass our configuration in the new environment.
new_env["COVERAGE_PROCESS_CONFIG"] = config.serialize()
if env.TESTING:
# The subprocesses need to use the same core as the main process.
new_env["COVERAGE_CORE"] = os.getenv("COVERAGE_CORE")
# When testing locally, we need to honor the pyc file location
# or they get written to the .tox directories and pollute the
# next run with a different core.
if (cache_prefix := os.getenv("PYTHONPYCACHEPREFIX")) is not None:
new_env["PYTHONPYCACHEPREFIX"] = cache_prefix
# Without this, it fails on PyPy and Ubuntu.
new_env["PATH"] = os.getenv("PATH")
old_execv(*args, **kwargs)
return coverage_execv_patch
# All the exec* and spawn* functions eventually call execv or execve.
os.execv = make_execv_patch("execv", os.execv)
os.execve = make_execv_patch("execve", os.execve)
def _patch_fork(debug: TDebugCtl) -> None:
"""Ensure Coverage is properly reset after a fork."""
from coverage.control import _after_fork_in_child
if env.WINDOWS:
raise CoverageException("patch=fork isn't supported yet on Windows.")
debug.write("Patching fork")
os.register_at_fork(after_in_child=_after_fork_in_child)
def _patch_subprocess(config: CoverageConfig, debug: TDebugCtl, make_pth_file: bool) -> None:
"""Write .pth files and set environment vars to measure subprocesses."""
debug.write("Patching subprocess")
if make_pth_file:
pth_files = create_pth_files(debug)
def delete_pth_files() -> None:
for p in pth_files:
debug.write(f"Deleting subprocess .pth file: {str(p)!r}")
p.unlink(missing_ok=True)
atexit.register(delete_pth_files)
assert config.config_file is not None
os.environ["COVERAGE_PROCESS_CONFIG"] = config.serialize()
# Writing .pth files is not obvious. On Windows, getsitepackages() returns two
# directories. A .pth file in the first will be run, but coverage isn't
# importable yet. We write into all the places we can, but with defensive
# import code.
PTH_CODE = """\
try:
import coverage
except:
pass
else:
coverage.process_startup()
"""
PTH_TEXT = f"import sys; exec({PTH_CODE!r})\n"
def create_pth_files(debug: TDebugCtl = NoDebugging()) -> list[Path]:
"""Create .pth files for measuring subprocesses."""
pth_files = []
for pth_dir in site.getsitepackages():
pth_file = Path(pth_dir) / f"subcover_{os.getpid()}.pth"
try:
if debug.should("patch"):
debug.write(f"Writing subprocess .pth file: {str(pth_file)!r}")
pth_file.write_text(PTH_TEXT, encoding="utf-8")
except OSError: # pragma: cant happen
continue
else:
pth_files.append(pth_file)
return pth_files
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/phystokens.py 0000644 0001751 0001751 00000016430 15073731535 017432 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Better tokenizing for coverage.py."""
from __future__ import annotations
import ast
import io
import keyword
import re
import sys
import token
import tokenize
from collections.abc import Iterable
from coverage import env
from coverage.types import TLineNo, TSourceTokenLines
TokenInfos = Iterable[tokenize.TokenInfo]
def _phys_tokens(toks: TokenInfos) -> TokenInfos:
"""Return all physical tokens, even line continuations.
tokenize.generate_tokens() doesn't return a token for the backslash that
continues lines. This wrapper provides those tokens so that we can
re-create a faithful representation of the original source.
Returns the same values as generate_tokens()
"""
last_line: str | None = None
last_lineno = -1
last_ttext: str = ""
for ttype, ttext, (slineno, scol), (elineno, ecol), ltext in toks:
if last_lineno != elineno:
if last_line and last_line.endswith("\\\n"):
# We are at the beginning of a new line, and the last line
# ended with a backslash. We probably have to inject a
# backslash token into the stream. Unfortunately, there's more
# to figure out. This code::
#
# usage = """\
# HEY THERE
# """
#
# triggers this condition, but the token text is::
#
# '"""\\\nHEY THERE\n"""'
#
# so we need to figure out if the backslash is already in the
# string token or not.
inject_backslash = True
if last_ttext.endswith("\\"):
inject_backslash = False
elif ttype == token.STRING:
if ( # pylint: disable=simplifiable-if-statement
last_line.endswith("\\\n")
and last_line.rstrip(" \\\n").endswith(last_ttext)
):
# Deal with special cases like such code::
#
# a = ["aaa",\ # there may be zero or more blanks between "," and "\".
# "bbb \
# ccc"]
#
inject_backslash = True
else:
# It's a multi-line string and the first line ends with
# a backslash, so we don't need to inject another.
inject_backslash = False
elif env.PYBEHAVIOR.fstring_syntax and ttype == token.FSTRING_MIDDLE:
inject_backslash = False
if inject_backslash:
# Figure out what column the backslash is in.
ccol = len(last_line.split("\n")[-2]) - 1
# Yield the token, with a fake token type.
yield tokenize.TokenInfo(
99999,
"\\\n",
(slineno, ccol),
(slineno, ccol + 2),
last_line,
)
last_line = ltext
if ttype not in (tokenize.NEWLINE, tokenize.NL):
last_ttext = ttext
yield tokenize.TokenInfo(ttype, ttext, (slineno, scol), (elineno, ecol), ltext)
last_lineno = elineno
def find_soft_key_lines(source: str) -> set[TLineNo]:
"""Helper for finding lines with soft keywords, like match/case lines."""
soft_key_lines: set[TLineNo] = set()
for node in ast.walk(ast.parse(source)):
if isinstance(node, ast.Match):
soft_key_lines.add(node.lineno)
for case in node.cases:
soft_key_lines.add(case.pattern.lineno)
elif sys.version_info >= (3, 12) and isinstance(node, ast.TypeAlias):
soft_key_lines.add(node.lineno)
return soft_key_lines
def source_token_lines(source: str) -> TSourceTokenLines:
"""Generate a series of lines, one for each line in `source`.
Each line is a list of pairs, each pair is a token::
[('key', 'def'), ('ws', ' '), ('nam', 'hello'), ('op', '('), ... ]
Each pair has a token class, and the token text.
If you concatenate all the token texts, and then join them with newlines,
you should have your original `source` back, with two differences:
trailing white space is not preserved, and a final line with no newline
is indistinguishable from a final line with a newline.
"""
ws_tokens = {token.INDENT, token.DEDENT, token.NEWLINE, tokenize.NL}
line: list[tuple[str, str]] = []
col = 0
source = source.expandtabs(8).replace("\r\n", "\n")
tokgen = generate_tokens(source)
soft_key_lines = find_soft_key_lines(source)
for ttype, ttext, (sline, scol), (_, ecol), _ in _phys_tokens(tokgen):
mark_start = True
for part in re.split("(\n)", ttext):
if part == "\n":
yield line
line = []
col = 0
mark_end = False
elif part == "":
mark_end = False
elif ttype in ws_tokens:
mark_end = False
else:
if env.PYBEHAVIOR.fstring_syntax and ttype == token.FSTRING_MIDDLE:
part = part.replace("{", "{{").replace("}", "}}")
ecol = scol + len(part)
if mark_start and scol > col:
line.append(("ws", " " * (scol - col)))
mark_start = False
tok_class = tokenize.tok_name.get(ttype, "xx").lower()[:3]
if ttype == token.NAME:
if keyword.iskeyword(ttext):
# Hard keywords are always keywords.
tok_class = "key"
elif keyword.issoftkeyword(ttext):
# Soft keywords appear at the start of their line.
if len(line) == 0:
is_start_of_line = True
elif (len(line) == 1) and line[0][0] == "ws":
is_start_of_line = True
else:
is_start_of_line = False
if is_start_of_line and sline in soft_key_lines:
tok_class = "key"
line.append((tok_class, part))
mark_end = True
scol = 0
if mark_end:
col = ecol
if line:
yield line
def generate_tokens(text: str) -> TokenInfos:
"""A helper around `tokenize.generate_tokens`.
Originally this was used to cache the results, but it didn't seem to make
reporting go faster, and caused issues with using too much memory.
"""
readline = io.StringIO(text).readline
return tokenize.generate_tokens(readline)
def source_encoding(source: bytes) -> str:
"""Determine the encoding for `source`, according to PEP 263.
`source` is a byte string: the text of the program.
Returns a string, the name of the encoding.
"""
readline = iter(source.splitlines(True)).__next__
return tokenize.detect_encoding(readline)[0]
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/plugin.py 0000644 0001751 0001751 00000052003 15073731535 016515 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""
.. versionadded:: 4.0
Plug-in interfaces for coverage.py.
Coverage.py supports a few different kinds of plug-ins that change its
behavior:
* File tracers implement tracing of non-Python file types.
* Configurers add custom configuration, using Python code to change the
configuration.
* Dynamic context switchers decide when the dynamic context has changed, for
example, to record what test function produced the coverage.
To write a coverage.py plug-in, create a module with a subclass of
:class:`~coverage.CoveragePlugin`. You will override methods in your class to
participate in various aspects of coverage.py's processing.
Different types of plug-ins have to override different methods.
Any plug-in can optionally implement :meth:`~coverage.CoveragePlugin.sys_info`
to provide debugging information about their operation.
Your module must also contain a ``coverage_init`` function that registers an
instance of your plug-in class::
import coverage
class MyPlugin(coverage.CoveragePlugin):
...
def coverage_init(reg, options):
reg.add_file_tracer(MyPlugin())
You use the `reg` parameter passed to your ``coverage_init`` function to
register your plug-in object. The registration method you call depends on
what kind of plug-in it is.
If your plug-in takes options, the `options` parameter is a dictionary of your
plug-in's options from the coverage.py configuration file. Use them however
you want to configure your object before registering it.
Coverage.py will store its own information on your plug-in object, using
attributes whose names start with ``_coverage_``. Don't be startled.
.. warning::
Plug-ins are imported by coverage.py before it begins measuring code.
If you write a plugin in your own project, it might import your product
code before coverage.py can start measuring. This can result in your
own code being reported as missing.
One solution is to put your plugins in your project tree, but not in
your importable Python package.
.. _file_tracer_plugins:
File Tracers
============
File tracers implement measurement support for non-Python files. File tracers
implement the :meth:`~coverage.CoveragePlugin.file_tracer` method to claim
files and the :meth:`~coverage.CoveragePlugin.file_reporter` method to report
on those files.
In your ``coverage_init`` function, use the ``add_file_tracer`` method to
register your file tracer.
.. _configurer_plugins:
Configurers
===========
.. versionadded:: 4.5
Configurers modify the configuration of coverage.py during start-up.
Configurers implement the :meth:`~coverage.CoveragePlugin.configure` method to
change the configuration.
In your ``coverage_init`` function, use the ``add_configurer`` method to
register your configurer.
.. _dynamic_context_plugins:
Dynamic Context Switchers
=========================
.. versionadded:: 5.0
Dynamic context switcher plugins implement the
:meth:`~coverage.CoveragePlugin.dynamic_context` method to dynamically compute
the context label for each measured frame.
Computed context labels are useful when you want to group measured data without
modifying the source code.
For example, you could write a plugin that checks `frame.f_code` to inspect
the currently executed method, and set the context label to a fully qualified
method name if it's an instance method of `unittest.TestCase` and the method
name starts with 'test'. Such a plugin would provide basic coverage grouping
by test and could be used with test runners that have no built-in coveragepy
support.
In your ``coverage_init`` function, use the ``add_dynamic_context`` method to
register your dynamic context switcher.
"""
from __future__ import annotations
import dataclasses
import functools
from collections.abc import Iterable
from types import FrameType
from typing import Any
from coverage import files
from coverage.misc import _needs_to_implement
from coverage.types import TArc, TConfigurable, TLineNo, TSourceTokenLines
class CoveragePlugin:
"""Base class for coverage.py plug-ins."""
_coverage_plugin_name: str
_coverage_enabled: bool
def file_tracer(self, filename: str) -> FileTracer | None: # pylint: disable=unused-argument
"""Get a :class:`FileTracer` object for a file.
Plug-in type: file tracer.
Every Python source file is offered to your plug-in to give it a chance
to take responsibility for tracing the file. If your plug-in can
handle the file, it should return a :class:`FileTracer` object.
Otherwise return None.
There is no way to register your plug-in for particular files.
Instead, this method is invoked for all files as they are executed,
and the plug-in decides whether it can trace the file or not.
Be prepared for `filename` to refer to all kinds of files that have
nothing to do with your plug-in.
The file name will be a Python file being executed. There are two
broad categories of behavior for a plug-in, depending on the kind of
files your plug-in supports:
* Static file names: each of your original source files has been
converted into a distinct Python file. Your plug-in is invoked with
the Python file name, and it maps it back to its original source
file.
* Dynamic file names: all of your source files are executed by the same
Python file. In this case, your plug-in implements
:meth:`FileTracer.dynamic_source_filename` to provide the actual
source file for each execution frame.
`filename` is a string, the path to the file being considered. This is
the absolute real path to the file. If you are comparing to other
paths, be sure to take this into account.
Returns a :class:`FileTracer` object to use to trace `filename`, or
None if this plug-in cannot trace this file.
"""
return None
def file_reporter(
self,
filename: str, # pylint: disable=unused-argument
) -> FileReporter | str: # str should be Literal["python"]
"""Get the :class:`FileReporter` class to use for a file.
Plug-in type: file tracer.
This will only be invoked if `filename` returns non-None from
:meth:`file_tracer`. It's an error to return None from this method.
Returns a :class:`FileReporter` object to use to report on `filename`,
or the string `"python"` to have coverage.py treat the file as Python.
"""
_needs_to_implement(self, "file_reporter")
def dynamic_context(
self,
frame: FrameType, # pylint: disable=unused-argument
) -> str | None:
"""Get the dynamically computed context label for `frame`.
Plug-in type: dynamic context.
This method is invoked for each frame when outside of a dynamic
context, to see if a new dynamic context should be started. If it
returns a string, a new context label is set for this and deeper
frames. The dynamic context ends when this frame returns.
Returns a string to start a new dynamic context, or None if no new
context should be started.
"""
return None
def find_executable_files(
self,
src_dir: str, # pylint: disable=unused-argument
) -> Iterable[str]:
"""Yield all of the executable files in `src_dir`, recursively.
Plug-in type: file tracer.
Executability is a plug-in-specific property, but generally means files
which would have been considered for coverage analysis, had they been
included automatically.
Returns or yields a sequence of strings, the paths to files that could
have been executed, including files that had been executed.
"""
return []
def configure(self, config: TConfigurable) -> None:
"""Modify the configuration of coverage.py.
Plug-in type: configurer.
This method is called during coverage.py start-up, to give your plug-in
a chance to change the configuration. The `config` parameter is an
object with :meth:`~coverage.Coverage.get_option` and
:meth:`~coverage.Coverage.set_option` methods. Do not call any other
methods on the `config` object.
"""
pass
def sys_info(self) -> Iterable[tuple[str, Any]]:
"""Get a list of information useful for debugging.
Plug-in type: any.
This method will be invoked for ``--debug=sys``. Your
plug-in can return any information it wants to be displayed.
Returns a list of pairs: `[(name, value), ...]`.
"""
return []
class CoveragePluginBase:
"""Plugins produce specialized objects, which point back to the original plugin."""
_coverage_plugin: CoveragePlugin
class FileTracer(CoveragePluginBase):
"""Support needed for files during the execution phase.
File tracer plug-ins implement subclasses of FileTracer to return from
their :meth:`~CoveragePlugin.file_tracer` method.
You may construct this object from :meth:`CoveragePlugin.file_tracer` any
way you like. A natural choice would be to pass the file name given to
`file_tracer`.
`FileTracer` objects should only be created in the
:meth:`CoveragePlugin.file_tracer` method.
See :ref:`howitworks` for details of the different coverage.py phases.
"""
def source_filename(self) -> str:
"""The source file name for this file.
This may be any file name you like. A key responsibility of a plug-in
is to own the mapping from Python execution back to whatever source
file name was originally the source of the code.
See :meth:`CoveragePlugin.file_tracer` for details about static and
dynamic file names.
Returns the file name to credit with this execution.
"""
_needs_to_implement(self, "source_filename")
def has_dynamic_source_filename(self) -> bool:
"""Does this FileTracer have dynamic source file names?
FileTracers can provide dynamically determined file names by
implementing :meth:`dynamic_source_filename`. Invoking that function
is expensive. To determine whether to invoke it, coverage.py uses the
result of this function to know if it needs to bother invoking
:meth:`dynamic_source_filename`.
See :meth:`CoveragePlugin.file_tracer` for details about static and
dynamic file names.
Returns True if :meth:`dynamic_source_filename` should be called to get
dynamic source file names.
"""
return False
def dynamic_source_filename(
self,
filename: str, # pylint: disable=unused-argument
frame: FrameType, # pylint: disable=unused-argument
) -> str | None:
"""Get a dynamically computed source file name.
Some plug-ins need to compute the source file name dynamically for each
frame.
This function will not be invoked if
:meth:`has_dynamic_source_filename` returns False.
Returns the source file name for this frame, or None if this frame
shouldn't be measured.
"""
return None
def line_number_range(self, frame: FrameType) -> tuple[TLineNo, TLineNo]:
"""Get the range of source line numbers for a given a call frame.
The call frame is examined, and the source line number in the original
file is returned. The return value is a pair of numbers, the starting
line number and the ending line number, both inclusive. For example,
returning (5, 7) means that lines 5, 6, and 7 should be considered
executed.
This function might decide that the frame doesn't indicate any lines
from the source file were executed. Return (-1, -1) in this case to
tell coverage.py that no lines should be recorded for this frame.
"""
lineno = frame.f_lineno
return lineno, lineno
@dataclasses.dataclass
class CodeRegion:
"""Data for a region of code found by :meth:`FileReporter.code_regions`."""
#: The kind of region, like `"function"` or `"class"`. Must be one of the
#: singular values returned by :meth:`FileReporter.code_region_kinds`.
kind: str
#: The name of the region. For example, a function or class name.
name: str
#: The line in the source file to link to when navigating to the region.
#: Can be a line not mentioned in `lines`.
start: int
#: The lines in the region. Should be lines that could be executed in the
#: region. For example, a class region includes all of the lines in the
#: methods of the class, but not the lines defining class attributes, since
#: they are executed on import, not as part of exercising the class. The
#: set can include non-executable lines like blanks and comments.
lines: set[int]
def __lt__(self, other: CodeRegion) -> bool:
"""To support sorting to make test-writing easier."""
if self.name == other.name:
return min(self.lines) < min(other.lines)
return self.name < other.name
@functools.total_ordering
class FileReporter(CoveragePluginBase):
"""Support needed for files during the analysis and reporting phases.
File tracer plug-ins implement a subclass of `FileReporter`, and return
instances from their :meth:`CoveragePlugin.file_reporter` method.
There are many methods here, but only :meth:`lines` is required, to provide
the set of executable lines in the file.
See :ref:`howitworks` for details of the different coverage.py phases.
"""
def __init__(self, filename: str) -> None:
"""Simple initialization of a `FileReporter`.
The `filename` argument is the path to the file being reported. This
will be available as the `.filename` attribute on the object. Other
method implementations on this base class rely on this attribute.
"""
self.filename = filename
def __repr__(self) -> str:
return f"<{self.__class__.__name__} filename={self.filename!r}>"
def relative_filename(self) -> str:
"""Get the relative file name for this file.
This file path will be displayed in reports. The default
implementation will supply the actual project-relative file path. You
only need to supply this method if you have an unusual syntax for file
paths.
"""
return files.relative_filename(self.filename)
def source(self) -> str:
"""Get the source for the file.
Returns a Unicode string.
The base implementation simply reads the `self.filename` file and
decodes it as UTF-8. Override this method if your file isn't readable
as a text file, or if you need other encoding support.
"""
with open(self.filename, encoding="utf-8") as f:
return f.read()
def lines(self) -> set[TLineNo]:
"""Get the executable lines in this file.
Your plug-in must determine which lines in the file were possibly
executable. This method returns a set of those line numbers.
Returns a set of line numbers.
"""
_needs_to_implement(self, "lines")
def excluded_lines(self) -> set[TLineNo]:
"""Get the excluded executable lines in this file.
Your plug-in can use any method it likes to allow the user to exclude
executable lines from consideration.
Returns a set of line numbers.
The base implementation returns the empty set.
"""
return set()
def translate_lines(self, lines: Iterable[TLineNo]) -> set[TLineNo]:
"""Translate recorded lines into reported lines.
Some file formats will want to report lines slightly differently than
they are recorded. For example, Python records the last line of a
multi-line statement, but reports are nicer if they mention the first
line.
Your plug-in can optionally define this method to perform these kinds
of adjustment.
`lines` is a sequence of integers, the recorded line numbers.
Returns a set of integers, the adjusted line numbers.
The base implementation returns the numbers unchanged.
"""
return set(lines)
def arcs(self) -> set[TArc]:
"""Get the executable arcs in this file.
To support branch coverage, your plug-in needs to be able to indicate
possible execution paths, as a set of line number pairs. Each pair is
a `(prev, next)` pair indicating that execution can transition from the
`prev` line number to the `next` line number.
Returns a set of pairs of line numbers. The default implementation
returns an empty set.
"""
return set()
def no_branch_lines(self) -> set[TLineNo]:
"""Get the lines excused from branch coverage in this file.
Your plug-in can use any method it likes to allow the user to exclude
lines from consideration of branch coverage.
Returns a set of line numbers.
The base implementation returns the empty set.
"""
return set()
def translate_arcs(self, arcs: Iterable[TArc]) -> set[TArc]:
"""Translate recorded arcs into reported arcs.
Similar to :meth:`translate_lines`, but for arcs. `arcs` is a set of
line number pairs.
Returns a set of line number pairs.
The default implementation returns `arcs` unchanged.
"""
return set(arcs)
def exit_counts(self) -> dict[TLineNo, int]:
"""Get a count of exits from that each line.
To determine which lines are branches, coverage.py looks for lines that
have more than one exit. This function creates a dict mapping each
executable line number to a count of how many exits it has.
To be honest, this feels wrong, and should be refactored. Let me know
if you attempt to implement this method in your plug-in...
"""
return {}
def missing_arc_description(
self,
start: TLineNo,
end: TLineNo,
executed_arcs: Iterable[TArc] | None = None, # pylint: disable=unused-argument
) -> str:
"""Provide an English sentence describing a missing arc.
The `start` and `end` arguments are the line numbers of the missing
arc. Negative numbers indicate entering or exiting code objects.
The `executed_arcs` argument is a set of line number pairs, the arcs
that were executed in this file.
By default, this simply returns the string "Line {start} didn't jump
to {end}".
"""
return f"Line {start} didn't jump to line {end}"
def arc_description(
self,
start: TLineNo, # pylint: disable=unused-argument
end: TLineNo,
) -> str:
"""Provide an English description of an arc's effect."""
return f"jump to line {end}"
def source_token_lines(self) -> TSourceTokenLines:
"""Generate a series of tokenized lines, one for each line in `source`.
These tokens are used for syntax-colored reports.
Each line is a list of pairs, each pair is a token::
[("key", "def"), ("ws", " "), ("nam", "hello"), ("op", "("), ... ]
Each pair has a token class, and the token text. The token classes
are:
* ``"com"``: a comment
* ``"key"``: a keyword
* ``"nam"``: a name, or identifier
* ``"num"``: a number
* ``"op"``: an operator
* ``"str"``: a string literal
* ``"ws"``: some white space
* ``"txt"``: some other kind of text
If you concatenate all the token texts, and then join them with
newlines, you should have your original source back.
The default implementation simply returns each line tagged as
``"txt"``.
"""
for line in self.source().splitlines():
yield [("txt", line)]
def code_regions(self) -> Iterable[CodeRegion]:
"""Identify regions in the source file for finer reporting than by file.
Returns an iterable of :class:`CodeRegion` objects. The kinds reported
should be in the possibilities returned by :meth:`code_region_kinds`.
"""
return []
def code_region_kinds(self) -> Iterable[tuple[str, str]]:
"""Return the kinds of code regions this plugin can find.
The returned pairs are the singular and plural forms of the kinds::
[
("function", "functions"),
("class", "classes"),
]
This will usually be hard-coded, but could also differ by the specific
source file involved.
"""
return []
def __eq__(self, other: Any) -> bool:
return isinstance(other, FileReporter) and self.filename == other.filename
def __lt__(self, other: Any) -> bool:
return isinstance(other, FileReporter) and self.filename < other.filename
# This object doesn't need to be hashed.
__hash__ = None # type: ignore[assignment]
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/plugin_support.py 0000644 0001751 0001751 00000024312 15073731535 020313 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Support for plugins."""
from __future__ import annotations
import os
import os.path
import sys
from collections.abc import Iterable, Iterator
from types import FrameType
from typing import Any, Callable
from coverage.exceptions import PluginError
from coverage.misc import isolate_module
from coverage.plugin import CoveragePlugin, FileReporter, FileTracer
from coverage.types import TArc, TConfigurable, TDebugCtl, TLineNo, TPluginConfig, TSourceTokenLines
os = isolate_module(os)
class Plugins:
"""The currently loaded collection of coverage.py plugins."""
def __init__(self, debug: TDebugCtl | None = None) -> None:
self.order: list[CoveragePlugin] = []
self.names: dict[str, CoveragePlugin] = {}
self.file_tracers: list[CoveragePlugin] = []
self.configurers: list[CoveragePlugin] = []
self.context_switchers: list[CoveragePlugin] = []
self.current_module: str | None = None
self.debug = debug
def load_from_config(
self,
modules: Iterable[str],
config: TPluginConfig,
) -> None:
"""Load plugin modules, and read their settings from configuration."""
for module in modules:
self.current_module = module
__import__(module)
mod = sys.modules[module]
coverage_init = getattr(mod, "coverage_init", None)
if not coverage_init:
raise PluginError(
f"Plugin module {module!r} didn't define a coverage_init function",
)
options = config.get_plugin_options(module)
coverage_init(self, options)
self.current_module = None
def load_from_callables(
self,
plugin_inits: Iterable[TCoverageInit],
) -> None:
"""Load plugins from callables provided."""
for fn in plugin_inits:
fn(self)
def add_file_tracer(self, plugin: CoveragePlugin) -> None:
"""Add a file tracer plugin.
`plugin` is an instance of a third-party plugin class. It must
implement the :meth:`CoveragePlugin.file_tracer` method.
"""
self._add_plugin(plugin, self.file_tracers)
def add_configurer(self, plugin: CoveragePlugin) -> None:
"""Add a configuring plugin.
`plugin` is an instance of a third-party plugin class. It must
implement the :meth:`CoveragePlugin.configure` method.
"""
self._add_plugin(plugin, self.configurers)
def add_dynamic_context(self, plugin: CoveragePlugin) -> None:
"""Add a dynamic context plugin.
`plugin` is an instance of a third-party plugin class. It must
implement the :meth:`CoveragePlugin.dynamic_context` method.
"""
self._add_plugin(plugin, self.context_switchers)
def add_noop(self, plugin: CoveragePlugin) -> None:
"""Add a plugin that does nothing.
This is only useful for testing the plugin support.
"""
self._add_plugin(plugin, None)
def _add_plugin(
self,
plugin: CoveragePlugin,
specialized: list[CoveragePlugin] | None,
) -> None:
"""Add a plugin object.
`plugin` is a :class:`CoveragePlugin` instance to add. `specialized`
is a list to append the plugin to.
"""
plugin_name = f"{self.current_module}.{plugin.__class__.__name__}"
if self.debug and self.debug.should("plugin"):
self.debug.write(f"Loaded plugin {self.current_module!r}: {plugin!r}")
labelled = LabelledDebug(f"plugin {self.current_module!r}", self.debug)
plugin = DebugPluginWrapper(plugin, labelled)
plugin._coverage_plugin_name = plugin_name
plugin._coverage_enabled = True
self.order.append(plugin)
self.names[plugin_name] = plugin
if specialized is not None:
specialized.append(plugin)
def __bool__(self) -> bool:
return bool(self.order)
def __iter__(self) -> Iterator[CoveragePlugin]:
return iter(self.order)
def get(self, plugin_name: str) -> CoveragePlugin:
"""Return a plugin by name."""
return self.names[plugin_name]
TCoverageInit = Callable[[Plugins], None]
class LabelledDebug:
"""A Debug writer, but with labels for prepending to the messages."""
def __init__(self, label: str, debug: TDebugCtl, prev_labels: Iterable[str] = ()):
self.labels = list(prev_labels) + [label]
self.debug = debug
def add_label(self, label: str) -> LabelledDebug:
"""Add a label to the writer, and return a new `LabelledDebug`."""
return LabelledDebug(label, self.debug, self.labels)
def message_prefix(self) -> str:
"""The prefix to use on messages, combining the labels."""
prefixes = self.labels + [""]
return ":\n".join(" " * i + label for i, label in enumerate(prefixes))
def write(self, message: str) -> None:
"""Write `message`, but with the labels prepended."""
self.debug.write(f"{self.message_prefix()}{message}")
class DebugPluginWrapper(CoveragePlugin):
"""Wrap a plugin, and use debug to report on what it's doing."""
def __init__(self, plugin: CoveragePlugin, debug: LabelledDebug) -> None:
super().__init__()
self.plugin = plugin
self.debug = debug
def file_tracer(self, filename: str) -> FileTracer | None:
tracer = self.plugin.file_tracer(filename)
self.debug.write(f"file_tracer({filename!r}) --> {tracer!r}")
if tracer:
debug = self.debug.add_label(f"file {filename!r}")
tracer = DebugFileTracerWrapper(tracer, debug)
return tracer
def file_reporter(self, filename: str) -> FileReporter | str:
reporter = self.plugin.file_reporter(filename)
assert isinstance(reporter, FileReporter)
self.debug.write(f"file_reporter({filename!r}) --> {reporter!r}")
if reporter:
debug = self.debug.add_label(f"file {filename!r}")
reporter = DebugFileReporterWrapper(filename, reporter, debug)
return reporter
def dynamic_context(self, frame: FrameType) -> str | None:
context = self.plugin.dynamic_context(frame)
self.debug.write(f"dynamic_context({frame!r}) --> {context!r}")
return context
def find_executable_files(self, src_dir: str) -> Iterable[str]:
executable_files = self.plugin.find_executable_files(src_dir)
self.debug.write(f"find_executable_files({src_dir!r}) --> {executable_files!r}")
return executable_files
def configure(self, config: TConfigurable) -> None:
self.debug.write(f"configure({config!r})")
self.plugin.configure(config)
def sys_info(self) -> Iterable[tuple[str, Any]]:
return self.plugin.sys_info()
class DebugFileTracerWrapper(FileTracer):
"""A debugging `FileTracer`."""
def __init__(self, tracer: FileTracer, debug: LabelledDebug) -> None:
self.tracer = tracer
self.debug = debug
def _show_frame(self, frame: FrameType) -> str:
"""A short string identifying a frame, for debug messages."""
filename = os.path.basename(frame.f_code.co_filename)
return f"{filename}@{frame.f_lineno}"
def source_filename(self) -> str:
sfilename = self.tracer.source_filename()
self.debug.write(f"source_filename() --> {sfilename!r}")
return sfilename
def has_dynamic_source_filename(self) -> bool:
has = self.tracer.has_dynamic_source_filename()
self.debug.write(f"has_dynamic_source_filename() --> {has!r}")
return has
def dynamic_source_filename(self, filename: str, frame: FrameType) -> str | None:
dyn = self.tracer.dynamic_source_filename(filename, frame)
self.debug.write(
"dynamic_source_filename({!r}, {}) --> {!r}".format(
filename,
self._show_frame(frame),
dyn,
)
)
return dyn
def line_number_range(self, frame: FrameType) -> tuple[TLineNo, TLineNo]:
pair = self.tracer.line_number_range(frame)
self.debug.write(f"line_number_range({self._show_frame(frame)}) --> {pair!r}")
return pair
class DebugFileReporterWrapper(FileReporter):
"""A debugging `FileReporter`."""
def __init__(self, filename: str, reporter: FileReporter, debug: LabelledDebug) -> None:
super().__init__(filename)
self.reporter = reporter
self.debug = debug
def relative_filename(self) -> str:
ret = self.reporter.relative_filename()
self.debug.write(f"relative_filename() --> {ret!r}")
return ret
def lines(self) -> set[TLineNo]:
ret = self.reporter.lines()
self.debug.write(f"lines() --> {ret!r}")
return ret
def excluded_lines(self) -> set[TLineNo]:
ret = self.reporter.excluded_lines()
self.debug.write(f"excluded_lines() --> {ret!r}")
return ret
def translate_lines(self, lines: Iterable[TLineNo]) -> set[TLineNo]:
ret = self.reporter.translate_lines(lines)
self.debug.write(f"translate_lines({lines!r}) --> {ret!r}")
return ret
def translate_arcs(self, arcs: Iterable[TArc]) -> set[TArc]:
ret = self.reporter.translate_arcs(arcs)
self.debug.write(f"translate_arcs({arcs!r}) --> {ret!r}")
return ret
def no_branch_lines(self) -> set[TLineNo]:
ret = self.reporter.no_branch_lines()
self.debug.write(f"no_branch_lines() --> {ret!r}")
return ret
def exit_counts(self) -> dict[TLineNo, int]:
ret = self.reporter.exit_counts()
self.debug.write(f"exit_counts() --> {ret!r}")
return ret
def arcs(self) -> set[TArc]:
ret = self.reporter.arcs()
self.debug.write(f"arcs() --> {ret!r}")
return ret
def source(self) -> str:
ret = self.reporter.source()
self.debug.write(f"source() --> {len(ret)} chars")
return ret
def source_token_lines(self) -> TSourceTokenLines:
ret = list(self.reporter.source_token_lines())
self.debug.write(f"source_token_lines() --> {len(ret)} tokens")
return ret
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/py.typed 0000644 0001751 0001751 00000000110 15073731535 016334 0 ustar 00runner runner # Marker file for PEP 561 to indicate that this package has type hints.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/python.py 0000644 0001751 0001751 00000020610 15073731535 016537 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Python source expertise for coverage.py"""
from __future__ import annotations
import os.path
import types
import zipimport
from collections.abc import Iterable
from typing import TYPE_CHECKING
from coverage import env
from coverage.exceptions import CoverageException, NoSource
from coverage.files import canonical_filename, relative_filename, zip_location
from coverage.misc import isolate_module, join_regex
from coverage.parser import PythonParser
from coverage.phystokens import source_encoding, source_token_lines
from coverage.plugin import CodeRegion, FileReporter
from coverage.regions import code_regions
from coverage.types import TArc, TLineNo, TMorf, TSourceTokenLines
if TYPE_CHECKING:
from coverage import Coverage
os = isolate_module(os)
def read_python_source(filename: str) -> bytes:
"""Read the Python source text from `filename`.
Returns bytes.
"""
with open(filename, "rb") as f:
source = f.read()
return source.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
def get_python_source(filename: str) -> str:
"""Return the source code, as unicode."""
base, ext = os.path.splitext(filename)
if ext == ".py" and env.WINDOWS:
exts = [".py", ".pyw"]
else:
exts = [ext]
source_bytes: bytes | None
for ext in exts:
try_filename = base + ext
if os.path.exists(try_filename):
# A regular text file: open it.
source_bytes = read_python_source(try_filename)
break
# Maybe it's in a zip file?
source_bytes = get_zip_bytes(try_filename)
if source_bytes is not None:
break
else:
# Couldn't find source.
raise NoSource(f"No source for code: '{filename}'.", slug="no-source")
# Replace \f because of http://bugs.python.org/issue19035
source_bytes = source_bytes.replace(b"\f", b" ")
source = source_bytes.decode(source_encoding(source_bytes), "replace")
# Python code should always end with a line with a newline.
if source and source[-1] != "\n":
source += "\n"
return source
def get_zip_bytes(filename: str) -> bytes | None:
"""Get data from `filename` if it is a zip file path.
Returns the bytestring data read from the zip file, or None if no zip file
could be found or `filename` isn't in it. The data returned will be
an empty string if the file is empty.
"""
zipfile_inner = zip_location(filename)
if zipfile_inner is not None:
zipfile, inner = zipfile_inner
try:
zi = zipimport.zipimporter(zipfile)
except zipimport.ZipImportError:
return None
try:
data = zi.get_data(inner)
except OSError:
return None
return data
return None
def source_for_file(filename: str) -> str:
"""Return the source filename for `filename`.
Given a file name being traced, return the best guess as to the source
file to attribute it to.
"""
if filename.endswith(".py"):
# .py files are themselves source files.
return filename
elif filename.endswith((".pyc", ".pyo")):
# Bytecode files probably have source files near them.
py_filename = filename[:-1]
if os.path.exists(py_filename):
# Found a .py file, use that.
return py_filename
if env.WINDOWS:
# On Windows, it could be a .pyw file.
pyw_filename = py_filename + "w"
if os.path.exists(pyw_filename):
return pyw_filename
# Didn't find source, but it's probably the .py file we want.
return py_filename
# No idea, just use the file name as-is.
return filename
def source_for_morf(morf: TMorf) -> str:
"""Get the source filename for the module-or-file `morf`."""
if hasattr(morf, "__file__") and morf.__file__:
filename = morf.__file__
elif isinstance(morf, types.ModuleType):
# A module should have had .__file__, otherwise we can't use it.
# This could be a PEP-420 namespace package.
raise CoverageException(f"Module {morf} has no file")
else:
filename = morf
filename = source_for_file(filename)
return filename
class PythonFileReporter(FileReporter):
"""Report support for a Python file."""
def __init__(self, morf: TMorf, coverage: Coverage | None = None) -> None:
self.coverage = coverage
filename = source_for_morf(morf)
fname = filename
canonicalize = True
if self.coverage is not None:
if self.coverage.config.relative_files:
canonicalize = False
if canonicalize:
fname = canonical_filename(filename)
super().__init__(fname)
if hasattr(morf, "__name__"):
name = morf.__name__.replace(".", os.sep)
if os.path.basename(filename).startswith("__init__."):
name += os.sep + "__init__"
name += ".py"
else:
name = relative_filename(filename)
self.relname = name
self._source: str | None = None
self._parser: PythonParser | None = None
self._excluded = None
def __repr__(self) -> str:
return f""
def relative_filename(self) -> str:
return self.relname
@property
def parser(self) -> PythonParser:
"""Lazily create a :class:`PythonParser`."""
assert self.coverage is not None
if self._parser is None:
self._parser = PythonParser(
filename=self.filename,
exclude=self.coverage._exclude_regex("exclude"),
)
self._parser.parse_source()
return self._parser
def lines(self) -> set[TLineNo]:
"""Return the line numbers of statements in the file."""
return self.parser.statements
def multiline_map(self) -> dict[TLineNo, TLineNo]:
"""A map of line numbers to first-line in a multi-line statement."""
return self.parser._multiline
def excluded_lines(self) -> set[TLineNo]:
"""Return the line numbers of statements in the file."""
return self.parser.excluded
def translate_lines(self, lines: Iterable[TLineNo]) -> set[TLineNo]:
return self.parser.translate_lines(lines)
def translate_arcs(self, arcs: Iterable[TArc]) -> set[TArc]:
return self.parser.translate_arcs(arcs)
def no_branch_lines(self) -> set[TLineNo]:
assert self.coverage is not None
no_branch = self.parser.lines_matching(
join_regex(self.coverage.config.partial_list + self.coverage.config.partial_always_list)
)
return no_branch
def arcs(self) -> set[TArc]:
return self.parser.arcs()
def exit_counts(self) -> dict[TLineNo, int]:
return self.parser.exit_counts()
def missing_arc_description(
self,
start: TLineNo,
end: TLineNo,
executed_arcs: Iterable[TArc] | None = None,
) -> str:
return self.parser.missing_arc_description(start, end)
def arc_description(self, start: TLineNo, end: TLineNo) -> str:
return self.parser.arc_description(start, end)
def source(self) -> str:
if self._source is None:
self._source = get_python_source(self.filename)
return self._source
def should_be_python(self) -> bool:
"""Does it seem like this file should contain Python?
This is used to decide if a file reported as part of the execution of
a program was really likely to have contained Python in the first
place.
"""
# Get the file extension.
_, ext = os.path.splitext(self.filename)
# Anything named *.py* should be Python.
if ext.startswith(".py"):
return True
# A file with no extension should be Python.
if not ext:
return True
# Everything else is probably not Python.
return False
def source_token_lines(self) -> TSourceTokenLines:
return source_token_lines(self.source())
def code_regions(self) -> Iterable[CodeRegion]:
return code_regions(self.source())
def code_region_kinds(self) -> Iterable[tuple[str, str]]:
return [
("function", "functions"),
("class", "classes"),
]
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/pytracer.py 0000644 0001751 0001751 00000035724 15073731535 017063 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Raw data collector for coverage.py."""
from __future__ import annotations
import atexit
import dis
import itertools
import sys
import threading
from types import FrameType, ModuleType
from typing import Any, Callable, cast
from coverage import env
from coverage.types import (
TArc,
TFileDisposition,
TLineNo,
Tracer,
TShouldStartContextFn,
TShouldTraceFn,
TTraceData,
TTraceFileData,
TTraceFn,
TWarnFn,
)
# I don't understand why, but if we use `cast(set[TLineNo], ...)` inside
# the _trace() function, we get some strange behavior on PyPy 3.10.
# Assigning these names here and using them below fixes the problem.
# See https://github.com/nedbat/coveragepy/issues/1902
set_TLineNo = set[TLineNo]
set_TArc = set[TArc]
# We need the YIELD_VALUE opcode below, in a comparison-friendly form.
# PYVERSIONS: RESUME is new in Python3.11
RESUME = dis.opmap.get("RESUME")
RETURN_VALUE = dis.opmap["RETURN_VALUE"]
if RESUME is None:
YIELD_VALUE = dis.opmap["YIELD_VALUE"]
YIELD_FROM = dis.opmap["YIELD_FROM"]
YIELD_FROM_OFFSET = 0 if env.PYPY else 2
else:
YIELD_VALUE = YIELD_FROM = YIELD_FROM_OFFSET = -1
# When running meta-coverage, this file can try to trace itself, which confuses
# everything. Don't trace ourselves.
THIS_FILE = __file__.rstrip("co")
class PyTracer(Tracer):
"""Python implementation of the raw data tracer."""
# Because of poor implementations of trace-function-manipulating tools,
# the Python trace function must be kept very simple. In particular, there
# must be only one function ever set as the trace function, both through
# sys.settrace, and as the return value from the trace function. Put
# another way, the trace function must always return itself. It cannot
# swap in other functions, or return None to avoid tracing a particular
# frame.
#
# The trace manipulator that introduced this restriction is DecoratorTools,
# which sets a trace function, and then later restores the pre-existing one
# by calling sys.settrace with a function it found in the current frame.
#
# Systems that use DecoratorTools (or similar trace manipulations) must use
# PyTracer to get accurate results. The command-line --timid argument is
# used to force the use of this tracer.
tracer_ids = itertools.count()
def __init__(self) -> None:
# Which tracer are we?
self.id = next(self.tracer_ids)
# Attributes set from the collector:
self.data: TTraceData
self.trace_arcs = False
self.should_trace: TShouldTraceFn
self.should_trace_cache: dict[str, TFileDisposition | None]
self.should_start_context: TShouldStartContextFn | None = None
self.switch_context: Callable[[str | None], None] | None = None
self.lock_data: Callable[[], None]
self.unlock_data: Callable[[], None]
self.warn: TWarnFn
# The threading module to use, if any.
self.threading: ModuleType | None = None
self.cur_file_data: TTraceFileData | None = None
self.last_line: TLineNo = 0
self.cur_file_name: str | None = None
self.context: str | None = None
self.started_context = False
# The data_stack parallels the Python call stack. Each entry is
# information about an active frame, a four-element tuple:
# [0] The TTraceData for this frame's file. Could be None if we
# aren't tracing this frame.
# [1] The current file name for the frame. None if we aren't tracing
# this frame.
# [2] The last line number executed in this frame.
# [3] Boolean: did this frame start a new context?
self.data_stack: list[tuple[TTraceFileData | None, str | None, TLineNo, bool]] = []
self.thread: threading.Thread | None = None
self.stopped = False
self._activity = False
self.in_atexit = False
# On exit, self.in_atexit = True
atexit.register(setattr, self, "in_atexit", True)
# Cache a bound method on the instance, so that we don't have to
# re-create a bound method object all the time.
self._cached_bound_method_trace: TTraceFn = self._trace
def __repr__(self) -> str:
points = sum(len(v) for v in self.data.values())
files = len(self.data)
return f""
def log(self, marker: str, *args: Any) -> None:
"""For hard-core logging of what this tracer is doing."""
with open("/tmp/debug_trace.txt", "a", encoding="utf-8") as f:
f.write(f"{marker} {self.id}[{len(self.data_stack)}]")
if 0: # if you want thread ids..
f.write( # type: ignore[unreachable]
".{:x}.{:x}".format(
self.thread.ident,
self.threading.current_thread().ident,
)
)
f.write(" {}".format(" ".join(map(str, args))))
if 0: # if you want callers..
f.write(" | ") # type: ignore[unreachable]
stack = " / ".join(
(fname or "???").rpartition("/")[-1] for _, fname, _, _ in self.data_stack
)
f.write(stack)
f.write("\n")
def _trace(
self,
frame: FrameType,
event: str,
arg: Any, # pylint: disable=unused-argument
lineno: TLineNo | None = None, # pylint: disable=unused-argument
) -> TTraceFn | None:
"""The trace function passed to sys.settrace."""
if THIS_FILE in frame.f_code.co_filename:
return None
# f = frame; code = f.f_code
# self.log(":", f"{code.co_filename} {f.f_lineno} {code.co_name}()", event)
if self.stopped and sys.gettrace() == self._cached_bound_method_trace: # pylint: disable=comparison-with-callable
# The PyTrace.stop() method has been called, possibly by another
# thread, let's deactivate ourselves now.
if 0:
f = frame # type: ignore[unreachable]
self.log("---\nX", f.f_code.co_filename, f.f_lineno)
while f:
self.log(">", f.f_code.co_filename, f.f_lineno, f.f_code.co_name, f.f_trace)
f = f.f_back
sys.settrace(None)
try:
self.cur_file_data, self.cur_file_name, self.last_line, self.started_context = (
self.data_stack.pop()
)
except IndexError:
self.log(
"Empty stack!",
frame.f_code.co_filename,
frame.f_lineno,
frame.f_code.co_name,
)
return None
# if event != "call" and frame.f_code.co_filename != self.cur_file_name:
# self.log("---\n*", frame.f_code.co_filename, self.cur_file_name, frame.f_lineno)
if event == "call":
# Should we start a new context?
if self.should_start_context and self.context is None:
context_maybe = self.should_start_context(frame) # pylint: disable=not-callable
if context_maybe is not None:
self.context = context_maybe
started_context = True
assert self.switch_context is not None
self.switch_context(self.context) # pylint: disable=not-callable
else:
started_context = False
else:
started_context = False
self.started_context = started_context
# Entering a new frame. Decide if we should trace in this file.
self._activity = True
self.data_stack.append(
(
self.cur_file_data,
self.cur_file_name,
self.last_line,
started_context,
),
)
# Improve tracing performance: when calling a function, both caller
# and callee are often within the same file. if that's the case, we
# don't have to re-check whether to trace the corresponding
# function (which is a little bit expensive since it involves
# dictionary lookups). This optimization is only correct if we
# didn't start a context.
filename = frame.f_code.co_filename
if filename != self.cur_file_name or started_context:
self.cur_file_name = filename
disp = self.should_trace_cache.get(filename)
if disp is None:
disp = self.should_trace(filename, frame)
self.should_trace_cache[filename] = disp
self.cur_file_data = None
if disp.trace:
tracename = disp.source_filename
assert tracename is not None
self.lock_data()
try:
if tracename not in self.data:
self.data[tracename] = set()
finally:
self.unlock_data()
self.cur_file_data = self.data[tracename]
else:
frame.f_trace_lines = False
elif not self.cur_file_data:
frame.f_trace_lines = False
# The call event is really a "start frame" event, and happens for
# function calls and re-entering generators. The f_lasti field is
# -1 for calls, and a real offset for generators. Use <0 as the
# line number for calls, and the real line number for generators.
if RESUME is not None:
# The current opcode is guaranteed to be RESUME. The argument
# determines what kind of resume it is.
oparg = frame.f_code.co_code[frame.f_lasti + 1]
real_call = (oparg == 0) # fmt: skip
else:
real_call = (getattr(frame, "f_lasti", -1) < 0) # fmt: skip
if real_call:
self.last_line = -frame.f_code.co_firstlineno
else:
self.last_line = frame.f_lineno
elif event == "line":
# Record an executed line.
if self.cur_file_data is not None:
flineno: TLineNo = frame.f_lineno
if self.trace_arcs:
cast(set_TArc, self.cur_file_data).add((self.last_line, flineno))
else:
cast(set_TLineNo, self.cur_file_data).add(flineno)
self.last_line = flineno
elif event == "return":
if self.trace_arcs and self.cur_file_data:
# Record an arc leaving the function, but beware that a
# "return" event might just mean yielding from a generator.
code = frame.f_code.co_code
lasti = frame.f_lasti
if RESUME is not None:
if len(code) == lasti + 2:
# A return from the end of a code object is a real return.
real_return = True
else:
# It is a real return if we aren't going to resume next.
if env.PYBEHAVIOR.lasti_is_yield:
lasti += 2
real_return = code[lasti] != RESUME
else:
if code[lasti] == RETURN_VALUE:
real_return = True
elif code[lasti] == YIELD_VALUE:
real_return = False
elif len(code) <= lasti + YIELD_FROM_OFFSET:
real_return = True
elif code[lasti + YIELD_FROM_OFFSET] == YIELD_FROM:
real_return = False
else:
real_return = True
if real_return:
first = frame.f_code.co_firstlineno
cast(set_TArc, self.cur_file_data).add((self.last_line, -first))
# Leaving this function, pop the filename stack.
self.cur_file_data, self.cur_file_name, self.last_line, self.started_context = (
self.data_stack.pop()
)
# Leaving a context?
if self.started_context:
assert self.switch_context is not None
self.context = None
self.switch_context(None) # pylint: disable=not-callable
return self._cached_bound_method_trace
def start(self) -> TTraceFn:
"""Start this Tracer.
Return a Python function suitable for use with sys.settrace().
"""
self.stopped = False
if self.threading:
if self.thread is None:
self.thread = self.threading.current_thread()
sys.settrace(self._cached_bound_method_trace)
return self._cached_bound_method_trace
def stop(self) -> None:
"""Stop this Tracer."""
# Get the active tracer callback before setting the stop flag to be
# able to detect if the tracer was changed prior to stopping it.
tf = sys.gettrace()
# Set the stop flag. The actual call to sys.settrace(None) will happen
# in the self._trace callback itself to make sure to call it from the
# right thread.
self.stopped = True
if self.threading:
assert self.thread is not None
if self.thread.ident != self.threading.current_thread().ident:
# Called on a different thread than started us: we can't unhook
# ourselves, but we've set the flag that we should stop, so we
# won't do any more tracing.
# self.log("~", "stopping on different threads")
return
# PyPy clears the trace function before running atexit functions,
# so don't warn if we are in atexit on PyPy and the trace function
# has changed to None. Metacoverage also messes this up, so don't
# warn if we are measuring ourselves.
suppress_warning = (env.PYPY and self.in_atexit and tf is None) or env.METACOV
if self.warn and not suppress_warning:
if tf != self._cached_bound_method_trace: # pylint: disable=comparison-with-callable
self.warn(
"Trace function changed, data is likely wrong: "
+ f"{tf!r} != {self._cached_bound_method_trace!r}",
slug="trace-changed",
)
def activity(self) -> bool:
"""Has there been any activity?"""
return self._activity
def reset_activity(self) -> None:
"""Reset the activity() flag."""
self._activity = False
def get_stats(self) -> dict[str, int] | None:
"""Return a dictionary of statistics, or None."""
return None
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/regions.py 0000644 0001751 0001751 00000010622 15073731535 016666 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Find functions and classes in Python code."""
from __future__ import annotations
import ast
import dataclasses
from typing import cast
from coverage.plugin import CodeRegion
@dataclasses.dataclass
class Context:
"""The nested named context of a function or class."""
name: str
kind: str
lines: set[int]
class RegionFinder:
"""An ast visitor that will find and track regions of code.
Functions and classes are tracked by name. Results are in the .regions
attribute.
"""
def __init__(self) -> None:
self.regions: list[CodeRegion] = []
self.context: list[Context] = []
def parse_source(self, source: str) -> None:
"""Parse `source` and walk the ast to populate the .regions attribute."""
self.handle_node(ast.parse(source))
def fq_node_name(self) -> str:
"""Get the current fully qualified name we're processing."""
return ".".join(c.name for c in self.context)
def handle_node(self, node: ast.AST) -> None:
"""Recursively handle any node."""
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
self.handle_FunctionDef(node)
elif isinstance(node, ast.ClassDef):
self.handle_ClassDef(node)
else:
self.handle_node_body(node)
def handle_node_body(self, node: ast.AST) -> None:
"""Recursively handle the nodes in this node's body, if any."""
for body_node in getattr(node, "body", ()):
self.handle_node(body_node)
def handle_FunctionDef(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
"""Called for `def` or `async def`."""
lines = set(range(node.body[0].lineno, cast(int, node.body[-1].end_lineno) + 1))
if self.context and self.context[-1].kind == "class":
# Function bodies are part of their enclosing class.
self.context[-1].lines |= lines
# Function bodies should be excluded from the nearest enclosing function.
for ancestor in reversed(self.context):
if ancestor.kind == "function":
ancestor.lines -= lines
break
self.context.append(Context(node.name, "function", lines))
self.regions.append(
CodeRegion(
kind="function",
name=self.fq_node_name(),
start=node.lineno,
lines=lines,
)
)
self.handle_node_body(node)
self.context.pop()
def handle_ClassDef(self, node: ast.ClassDef) -> None:
"""Called for `class`."""
# The lines for a class are the lines in the methods of the class.
# We start empty, and count on visit_FunctionDef to add the lines it
# finds.
lines: set[int] = set()
self.context.append(Context(node.name, "class", lines))
self.regions.append(
CodeRegion(
kind="class",
name=self.fq_node_name(),
start=node.lineno,
lines=lines,
)
)
self.handle_node_body(node)
self.context.pop()
# Class bodies should be excluded from the enclosing classes.
for ancestor in reversed(self.context):
if ancestor.kind == "class":
ancestor.lines -= lines
def code_regions(source: str) -> list[CodeRegion]:
"""Find function and class regions in source code.
Analyzes the code in `source`, and returns a list of :class:`CodeRegion`
objects describing functions and classes as regions of the code::
[
CodeRegion(kind="function", name="func1", start=8, lines={10, 11, 12}),
CodeRegion(kind="function", name="MyClass.method", start=30, lines={34, 35, 36}),
CodeRegion(kind="class", name="MyClass", start=25, lines={34, 35, 36}),
]
The line numbers will include comments and blank lines. Later processing
will need to ignore those lines as needed.
Nested functions and classes are excluded from their enclosing region. No
line should be reported as being part of more than one function, or more
than one class. Lines in methods are reported as being in a function and
in a class.
"""
rf = RegionFinder()
rf.parse_source(source)
return rf.regions
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/report.py 0000644 0001751 0001751 00000025100 15073731535 016530 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Summary reporting"""
from __future__ import annotations
import sys
from collections.abc import Iterable
from typing import IO, TYPE_CHECKING, Any
from coverage.exceptions import ConfigError, NoDataError
from coverage.misc import human_sorted_items, plural
from coverage.plugin import FileReporter
from coverage.report_core import get_analysis_to_report
from coverage.results import Analysis, Numbers
from coverage.types import TMorf
if TYPE_CHECKING:
from coverage import Coverage
class SummaryReporter:
"""A reporter for writing the summary report."""
def __init__(self, coverage: Coverage) -> None:
self.coverage = coverage
self.config = self.coverage.config
self.branches = coverage.get_data().has_arcs()
self.outfile: IO[str] | None = None
self.output_format = self.config.format or "text"
if self.output_format not in {"text", "markdown", "total"}:
raise ConfigError(f"Unknown report format choice: {self.output_format!r}")
self.fr_analyses: list[tuple[FileReporter, Analysis]] = []
self.skipped_count = 0
self.empty_count = 0
self.total = Numbers(precision=self.config.precision)
def write(self, line: str) -> None:
"""Write a line to the output, adding a newline."""
assert self.outfile is not None
self.outfile.write(line.rstrip())
self.outfile.write("\n")
def write_items(self, items: Iterable[str]) -> None:
"""Write a list of strings, joined together."""
self.write("".join(items))
def report_text(
self,
header: list[str],
lines_values: list[list[Any]],
total_line: list[Any],
end_lines: list[str],
) -> None:
"""Internal method that prints report data in text format.
`header` is a list with captions.
`lines_values` is list of lists of sortable values.
`total_line` is a list with values of the total line.
`end_lines` is a list of ending lines with information about skipped files.
"""
# Prepare the formatting strings, header, and column sorting.
max_name = max([len(line[0]) for line in lines_values] + [5]) + 1
max_n = max(len(total_line[header.index("Cover")]) + 2, len(" Cover")) + 1
max_n = max([max_n] + [len(line[header.index("Cover")]) + 2 for line in lines_values])
formats = dict(
Name="{:{name_len}}",
Stmts="{:>7}",
Miss="{:>7}",
Branch="{:>7}",
BrPart="{:>7}",
Cover="{:>{n}}",
Missing="{:>10}",
)
header_items = [formats[item].format(item, name_len=max_name, n=max_n) for item in header]
header_str = "".join(header_items)
rule = "-" * len(header_str)
# Write the header
self.write(header_str)
self.write(rule)
# Write the data lines
formats.update(
dict(
Cover="{:>{n}}%",
Missing=" {:9}",
)
)
for values in lines_values:
self.write_items(
(
formats[item].format(str(value), name_len=max_name, n=max_n - 1)
for item, value in zip(header, values)
)
)
# Write a TOTAL line
if lines_values:
self.write(rule)
self.write_items(
(
formats[item].format(str(value), name_len=max_name, n=max_n - 1)
for item, value in zip(header, total_line)
)
)
for end_line in end_lines:
self.write(end_line)
def report_markdown(
self,
header: list[str],
lines_values: list[list[Any]],
total_line: list[Any],
end_lines: list[str],
) -> None:
"""Internal method that prints report data in markdown format.
`header` is a list with captions.
`lines_values` is a sorted list of lists containing coverage information.
`total_line` is a list with values of the total line.
`end_lines` is a list of ending lines with information about skipped files.
"""
# Prepare the formatting strings, header, and column sorting.
max_name = max((len(line[0].replace("_", "\\_")) for line in lines_values), default=0)
max_name = max(max_name, len("**TOTAL**")) + 1
formats = dict(
Name="| {:{name_len}}|",
Stmts="{:>9} |",
Miss="{:>9} |",
Branch="{:>9} |",
BrPart="{:>9} |",
Cover="{:>{n}} |",
Missing="{:>10} |",
)
max_n = max(len(total_line[header.index("Cover")]) + 6, len(" Cover "))
header_items = [formats[item].format(item, name_len=max_name, n=max_n) for item in header]
header_str = "".join(header_items)
rule_str = "|" + " ".join(
["- |".rjust(len(header_items[0]) - 1, "-")]
+ ["-: |".rjust(len(item) - 1, "-") for item in header_items[1:]],
)
# Write the header
self.write(header_str)
self.write(rule_str)
# Write the data lines
for values in lines_values:
formats.update(
dict(
Cover="{:>{n}}% |",
)
)
self.write_items(
(
formats[item].format(
str(value).replace("_", "\\_"), name_len=max_name, n=max_n - 1
)
for item, value in zip(header, values)
)
)
# Write the TOTAL line
formats.update(
dict(
Name="|{:>{name_len}} |",
Cover="{:>{n}} |",
),
)
total_line_items: list[str] = []
for item, value in zip(header, total_line):
if value == "":
insert = value
elif item == "Cover":
insert = f" **{value}%**"
else:
insert = f" **{value}**"
total_line_items += formats[item].format(insert, name_len=max_name, n=max_n)
self.write_items(total_line_items)
for end_line in end_lines:
self.write(end_line)
def report(self, morfs: Iterable[TMorf] | None, outfile: IO[str] | None = None) -> float:
"""Writes a report summarizing coverage statistics per module.
`outfile` is a text-mode file object to write the summary to.
"""
self.outfile = outfile or sys.stdout
self.coverage.get_data().set_query_contexts(self.config.report_contexts)
for fr, analysis in get_analysis_to_report(self.coverage, morfs):
self.report_one_file(fr, analysis)
if not self.total.n_files and not self.skipped_count:
raise NoDataError("No data to report.")
if self.output_format == "total":
self.write(self.total.pc_covered_str)
else:
self.tabular_report()
return self.total.pc_covered
def tabular_report(self) -> None:
"""Writes tabular report formats."""
# Prepare the header line and column sorting.
header = ["Name", "Stmts", "Miss"]
if self.branches:
header += ["Branch", "BrPart"]
header += ["Cover"]
if self.config.show_missing:
header += ["Missing"]
column_order = dict(name=0, stmts=1, miss=2, cover=-1)
if self.branches:
column_order.update(dict(branch=3, brpart=4))
# `lines_values` is list of lists of sortable values.
lines_values = []
for fr, analysis in self.fr_analyses:
nums = analysis.numbers
args = [fr.relative_filename(), nums.n_statements, nums.n_missing]
if self.branches:
args += [nums.n_branches, nums.n_partial_branches]
args += [nums.pc_covered_str]
if self.config.show_missing:
args += [analysis.missing_formatted(branches=True)]
args += [nums.pc_covered]
lines_values.append(args)
# Line sorting.
sort_option = (self.config.sort or "name").lower()
reverse = False
if sort_option[0] == "-":
reverse = True
sort_option = sort_option[1:]
elif sort_option[0] == "+":
sort_option = sort_option[1:]
sort_idx = column_order.get(sort_option)
if sort_idx is None:
raise ConfigError(f"Invalid sorting option: {self.config.sort!r}")
if sort_option == "name":
lines_values = human_sorted_items(lines_values, reverse=reverse)
else:
lines_values.sort(
key=lambda line: (line[sort_idx], line[0]),
reverse=reverse,
)
# Calculate total if we had at least one file.
total_line = ["TOTAL", self.total.n_statements, self.total.n_missing]
if self.branches:
total_line += [self.total.n_branches, self.total.n_partial_branches]
total_line += [self.total.pc_covered_str]
if self.config.show_missing:
total_line += [""]
# Create other final lines.
end_lines = []
if self.config.skip_covered and self.skipped_count:
files = plural(self.skipped_count, "file")
end_lines.append(
f"\n{self.skipped_count} {files} skipped due to complete coverage.",
)
if self.config.skip_empty and self.empty_count:
files = plural(self.empty_count, "file")
end_lines.append(f"\n{self.empty_count} empty {files} skipped.")
if self.output_format == "markdown":
formatter = self.report_markdown
else:
formatter = self.report_text
formatter(header, lines_values, total_line, end_lines)
def report_one_file(self, fr: FileReporter, analysis: Analysis) -> None:
"""Report on just one file, the callback from report()."""
nums = analysis.numbers
self.total += nums
no_missing_lines = (nums.n_missing == 0) # fmt: skip
no_missing_branches = (nums.n_partial_branches == 0) # fmt: skip
if self.config.skip_covered and no_missing_lines and no_missing_branches:
# Don't report on 100% files.
self.skipped_count += 1
elif self.config.skip_empty and nums.n_statements == 0:
# Don't report on empty files.
self.empty_count += 1
else:
self.fr_analyses.append((fr, analysis))
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/report_core.py 0000644 0001751 0001751 00000007724 15073731535 017554 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Reporter foundation for coverage.py."""
from __future__ import annotations
import sys
from collections.abc import Iterable, Iterator
from typing import IO, TYPE_CHECKING, Callable, Protocol
from coverage.exceptions import NoDataError, NotPython
from coverage.files import GlobMatcher, prep_patterns
from coverage.misc import ensure_dir_for_file, file_be_gone
from coverage.plugin import FileReporter
from coverage.results import Analysis
from coverage.types import TMorf
if TYPE_CHECKING:
from coverage import Coverage
class Reporter(Protocol):
"""What we expect of reporters."""
report_type: str
def report(self, morfs: Iterable[TMorf] | None, outfile: IO[str]) -> float:
"""Generate a report of `morfs`, written to `outfile`."""
def render_report(
output_path: str,
reporter: Reporter,
morfs: Iterable[TMorf] | None,
msgfn: Callable[[str], None],
) -> float:
"""Run a one-file report generator, managing the output file.
This function ensures the output file is ready to be written to. Then writes
the report to it. Then closes the file and cleans up.
"""
file_to_close = None
delete_file = False
if output_path == "-":
outfile = sys.stdout
else:
# Ensure that the output directory is created; done here because this
# report pre-opens the output file. HtmlReporter does this on its own
# because its task is more complex, being multiple files.
ensure_dir_for_file(output_path)
outfile = open(output_path, "w", encoding="utf-8")
file_to_close = outfile
delete_file = True
try:
ret = reporter.report(morfs, outfile=outfile)
if file_to_close is not None:
msgfn(f"Wrote {reporter.report_type} to {output_path}")
delete_file = False
return ret
finally:
if file_to_close is not None:
file_to_close.close()
if delete_file:
file_be_gone(output_path) # pragma: part covered (doesn't return)
def get_analysis_to_report(
coverage: Coverage,
morfs: Iterable[TMorf] | None,
) -> Iterator[tuple[FileReporter, Analysis]]:
"""Get the files to report on.
For each morf in `morfs`, if it should be reported on (based on the omit
and include configuration options), yield a pair, the `FileReporter` and
`Analysis` for the morf.
"""
fr_morfs = coverage._get_file_reporters(morfs)
config = coverage.config
if config.report_include:
matcher = GlobMatcher(prep_patterns(config.report_include), "report_include")
fr_morfs = [(fr, morf) for (fr, morf) in fr_morfs if matcher.match(fr.filename)]
if config.report_omit:
matcher = GlobMatcher(prep_patterns(config.report_omit), "report_omit")
fr_morfs = [(fr, morf) for (fr, morf) in fr_morfs if not matcher.match(fr.filename)]
if not fr_morfs:
raise NoDataError("No data to report.")
for fr, morf in sorted(fr_morfs):
try:
analysis = coverage._analyze(morf)
except NotPython:
# Only report errors for .py files, and only if we didn't
# explicitly suppress those errors.
# NotPython is only raised by PythonFileReporter, which has a
# should_be_python() method.
if fr.should_be_python(): # type: ignore[attr-defined]
if config.ignore_errors:
msg = f"Couldn't parse Python file '{fr.filename}'"
coverage._warn(msg, slug="couldnt-parse")
else:
raise
except Exception as exc:
if config.ignore_errors:
msg = f"Couldn't parse '{fr.filename}': {exc}".rstrip()
coverage._warn(msg, slug="couldnt-parse")
else:
raise
else:
yield (fr, analysis)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/results.py 0000644 0001751 0001751 00000037345 15073731535 016734 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Results of coverage measurement."""
from __future__ import annotations
import collections
import dataclasses
from collections.abc import Iterable
from typing import TYPE_CHECKING
from coverage.exceptions import ConfigError
from coverage.misc import nice_pair
from coverage.types import TArc, TLineNo
if TYPE_CHECKING:
from coverage.data import CoverageData
from coverage.plugin import FileReporter
def analysis_from_file_reporter(
data: CoverageData,
precision: int,
file_reporter: FileReporter,
filename: str,
) -> Analysis:
"""Create an Analysis from a FileReporter."""
has_arcs = data.has_arcs()
statements = file_reporter.lines()
excluded = file_reporter.excluded_lines()
executed = file_reporter.translate_lines(data.lines(filename) or [])
if has_arcs:
arc_possibilities_set = file_reporter.arcs()
arcs: Iterable[TArc] = data.arcs(filename) or []
arcs = file_reporter.translate_arcs(arcs)
# Reduce the set of arcs to the ones that could be branches.
dests = collections.defaultdict(set)
for fromno, tono in arc_possibilities_set:
dests[fromno].add(tono)
single_dests = {
fromno: list(tonos)[0] for fromno, tonos in dests.items() if len(tonos) == 1
}
new_arcs = set()
for fromno, tono in arcs:
if fromno != tono:
new_arcs.add((fromno, tono))
else:
if fromno in single_dests:
new_arcs.add((fromno, single_dests[fromno]))
arcs_executed_set = file_reporter.translate_arcs(new_arcs)
exit_counts = file_reporter.exit_counts()
no_branch = file_reporter.no_branch_lines()
else:
arc_possibilities_set = set()
arcs_executed_set = set()
exit_counts = {}
no_branch = set()
return Analysis(
precision=precision,
filename=filename,
has_arcs=has_arcs,
statements=statements,
excluded=excluded,
executed=executed,
arc_possibilities_set=arc_possibilities_set,
arcs_executed_set=arcs_executed_set,
exit_counts=exit_counts,
no_branch=no_branch,
)
@dataclasses.dataclass
class Analysis:
"""The results of analyzing a FileReporter."""
precision: int
filename: str
has_arcs: bool
statements: set[TLineNo]
excluded: set[TLineNo]
executed: set[TLineNo]
arc_possibilities_set: set[TArc]
arcs_executed_set: set[TArc]
exit_counts: dict[TLineNo, int]
no_branch: set[TLineNo]
def __post_init__(self) -> None:
self.arc_possibilities = sorted(self.arc_possibilities_set)
self.arcs_executed = sorted(self.arcs_executed_set)
self.missing = self.statements - self.executed
if self.has_arcs:
n_branches = self._total_branches()
mba = self.missing_branch_arcs()
n_partial_branches = sum(len(v) for k, v in mba.items() if k not in self.missing)
n_missing_branches = sum(len(v) for k, v in mba.items())
else:
n_branches = n_partial_branches = n_missing_branches = 0
self.numbers = Numbers(
precision=self.precision,
n_files=1,
n_statements=len(self.statements),
n_excluded=len(self.excluded),
n_missing=len(self.missing),
n_branches=n_branches,
n_partial_branches=n_partial_branches,
n_missing_branches=n_missing_branches,
)
def missing_formatted(self, branches: bool = False) -> str:
"""The missing line numbers, formatted nicely.
Returns a string like "1-2, 5-11, 13-14".
If `branches` is true, includes the missing branch arcs also.
"""
if branches and self.has_arcs:
arcs = self.missing_branch_arcs().items()
else:
arcs = None
return format_lines(self.statements, self.missing, arcs=arcs)
def arcs_missing(self) -> list[TArc]:
"""Returns a sorted list of the un-executed arcs in the code."""
missing = (
p
for p in self.arc_possibilities
if p not in self.arcs_executed_set
and p[0] not in self.no_branch
and p[1] not in self.excluded
)
return sorted(missing)
def _branch_lines(self) -> list[TLineNo]:
"""Returns a list of line numbers that have more than one exit."""
return [l1 for l1, count in self.exit_counts.items() if count > 1]
def _total_branches(self) -> int:
"""How many total branches are there?"""
return sum(count for count in self.exit_counts.values() if count > 1)
def missing_branch_arcs(self) -> dict[TLineNo, list[TLineNo]]:
"""Return arcs that weren't executed from branch lines.
Returns {l1:[l2a,l2b,...], ...}
"""
missing = self.arcs_missing()
branch_lines = set(self._branch_lines())
mba = collections.defaultdict(list)
for l1, l2 in missing:
assert l1 != l2, f"In {self.filename}, didn't expect {l1} == {l2}"
if l1 in branch_lines:
mba[l1].append(l2)
return mba
def executed_branch_arcs(self) -> dict[TLineNo, list[TLineNo]]:
"""Return arcs that were executed from branch lines.
Only include ones that we considered possible.
Returns {l1:[l2a,l2b,...], ...}
"""
branch_lines = set(self._branch_lines())
eba = collections.defaultdict(list)
for l1, l2 in self.arcs_executed:
assert l1 != l2, f"Oops: Didn't think this could happen: {l1 = }, {l2 = }"
if (l1, l2) not in self.arc_possibilities_set:
continue
if l1 in branch_lines:
eba[l1].append(l2)
return eba
def branch_stats(self) -> dict[TLineNo, tuple[int, int]]:
"""Get stats about branches.
Returns a dict mapping line numbers to a tuple:
(total_exits, taken_exits).
"""
missing_arcs = self.missing_branch_arcs()
stats = {}
for lnum in self._branch_lines():
exits = self.exit_counts[lnum]
missing = len(missing_arcs[lnum])
stats[lnum] = (exits, exits - missing)
return stats
TRegionLines = frozenset[TLineNo]
class AnalysisNarrower:
"""
For reducing an `Analysis` to a subset of its lines.
Originally this was a simpler method on Analysis, but that led to quadratic
behavior. This class does the bulk of the work up-front to provide the
same results in linear time.
Create an AnalysisNarrower from an Analysis, bulk-add region lines to it
with `add_regions`, then individually request new narrowed Analysis objects
for each region with `narrow`. Doing most of the work in limited calls to
`add_regions` lets us avoid poor performance.
"""
# In this class, regions are represented by a frozenset of their lines.
def __init__(self, analysis: Analysis) -> None:
self.analysis = analysis
self.region2arc_possibilities: dict[TRegionLines, set[TArc]] = collections.defaultdict(set)
self.region2arc_executed: dict[TRegionLines, set[TArc]] = collections.defaultdict(set)
self.region2exit_counts: dict[TRegionLines, dict[TLineNo, int]] = collections.defaultdict(
dict
)
def add_regions(self, liness: Iterable[set[TLineNo]]) -> None:
"""
Pre-process a number of sets of line numbers. Later calls to `narrow`
with one of these sets will provide a narrowed Analysis.
"""
if self.analysis.has_arcs:
line2region: dict[TLineNo, TRegionLines] = {}
for lines in liness:
fzlines = frozenset(lines)
for line in lines:
line2region[line] = fzlines
def collect_arcs(
arc_set: set[TArc],
region2arcs: dict[TRegionLines, set[TArc]],
) -> None:
for a, b in arc_set:
if r := line2region.get(a):
region2arcs[r].add((a, b))
if r := line2region.get(b):
region2arcs[r].add((a, b))
collect_arcs(self.analysis.arc_possibilities_set, self.region2arc_possibilities)
collect_arcs(self.analysis.arcs_executed_set, self.region2arc_executed)
for lno, num in self.analysis.exit_counts.items():
if r := line2region.get(lno):
self.region2exit_counts[r][lno] = num
def narrow(self, lines: set[TLineNo]) -> Analysis:
"""Create a narrowed Analysis.
The current analysis is copied to make a new one that only considers
the lines in `lines`.
"""
# Technically, the set intersections in this method are still O(N**2)
# since this method is called N times, but they're very fast and moving
# them to `add_regions` won't avoid the quadratic time.
statements = self.analysis.statements & lines
excluded = self.analysis.excluded & lines
executed = self.analysis.executed & lines
if self.analysis.has_arcs:
fzlines = frozenset(lines)
arc_possibilities_set = self.region2arc_possibilities[fzlines]
arcs_executed_set = self.region2arc_executed[fzlines]
exit_counts = self.region2exit_counts[fzlines]
no_branch = self.analysis.no_branch & lines
else:
arc_possibilities_set = set()
arcs_executed_set = set()
exit_counts = {}
no_branch = set()
return Analysis(
precision=self.analysis.precision,
filename=self.analysis.filename,
has_arcs=self.analysis.has_arcs,
statements=statements,
excluded=excluded,
executed=executed,
arc_possibilities_set=arc_possibilities_set,
arcs_executed_set=arcs_executed_set,
exit_counts=exit_counts,
no_branch=no_branch,
)
@dataclasses.dataclass
class Numbers:
"""The numerical results of measuring coverage.
This holds the basic statistics from `Analysis`, and is used to roll
up statistics across files.
"""
precision: int = 0
n_files: int = 0
n_statements: int = 0
n_excluded: int = 0
n_missing: int = 0
n_branches: int = 0
n_partial_branches: int = 0
n_missing_branches: int = 0
@property
def n_executed(self) -> int:
"""Returns the number of executed statements."""
return self.n_statements - self.n_missing
@property
def n_executed_branches(self) -> int:
"""Returns the number of executed branches."""
return self.n_branches - self.n_missing_branches
@property
def pc_covered(self) -> float:
"""Returns a single percentage value for coverage."""
if self.n_statements > 0:
numerator, denominator = self.ratio_covered
pc_cov = (100.0 * numerator) / denominator
else:
pc_cov = 100.0
return pc_cov
@property
def pc_covered_str(self) -> str:
"""Returns the percent covered, as a string, without a percent sign.
Note that "0" is only returned when the value is truly zero, and "100"
is only returned when the value is truly 100. Rounding can never
result in either "0" or "100".
"""
return display_covered(self.pc_covered, self.precision)
@property
def ratio_covered(self) -> tuple[int, int]:
"""Return a numerator and denominator for the coverage ratio."""
numerator = self.n_executed + self.n_executed_branches
denominator = self.n_statements + self.n_branches
return numerator, denominator
def __add__(self, other: Numbers) -> Numbers:
return Numbers(
self.precision,
self.n_files + other.n_files,
self.n_statements + other.n_statements,
self.n_excluded + other.n_excluded,
self.n_missing + other.n_missing,
self.n_branches + other.n_branches,
self.n_partial_branches + other.n_partial_branches,
self.n_missing_branches + other.n_missing_branches,
)
def __radd__(self, other: int) -> Numbers:
# Implementing 0+Numbers allows us to sum() a list of Numbers.
assert other == 0 # we only ever call it this way.
return self
def display_covered(pc: float, precision: int) -> str:
"""Return a displayable total percentage, as a string.
Note that "0" is only returned when the value is truly zero, and "100"
is only returned when the value is truly 100. Rounding can never
result in either "0" or "100".
"""
near0 = 1.0 / 10**precision
if 0 < pc < near0:
pc = near0
elif (100.0 - near0) < pc < 100:
pc = 100.0 - near0
else:
pc = round(pc, precision)
return f"{pc:.{precision}f}"
def _line_ranges(
statements: Iterable[TLineNo],
lines: Iterable[TLineNo],
) -> list[tuple[TLineNo, TLineNo]]:
"""Produce a list of ranges for `format_lines`."""
statements = sorted(statements)
lines = sorted(lines)
pairs = []
start: TLineNo | None = None
lidx = 0
for stmt in statements:
if lidx >= len(lines):
break
if stmt == lines[lidx]:
lidx += 1
if not start:
start = stmt
end = stmt
elif start:
pairs.append((start, end))
start = None
if start:
pairs.append((start, end))
return pairs
def format_lines(
statements: Iterable[TLineNo],
lines: Iterable[TLineNo],
arcs: Iterable[tuple[TLineNo, list[TLineNo]]] | None = None,
) -> str:
"""Nicely format a list of line numbers.
Format a list of line numbers for printing by coalescing groups of lines as
long as the lines represent consecutive statements. This will coalesce
even if there are gaps between statements.
For example, if `statements` is [1,2,3,4,5,10,11,12,13,14] and
`lines` is [1,2,5,10,11,13,14] then the result will be "1-2, 5-11, 13-14".
Both `lines` and `statements` can be any iterable. All of the elements of
`lines` must be in `statements`, and all of the values must be positive
integers.
If `arcs` is provided, they are (start,[end,end,end]) pairs that will be
included in the output as long as start isn't in `lines`.
"""
line_items = [(pair[0], nice_pair(pair)) for pair in _line_ranges(statements, lines)]
if arcs is not None:
line_exits = sorted(arcs)
for line, exits in line_exits:
for ex in sorted(exits):
if line not in lines and ex not in lines:
dest = ex if ex > 0 else "exit"
line_items.append((line, f"{line}->{dest}"))
ret = ", ".join(t[-1] for t in sorted(line_items))
return ret
def should_fail_under(total: float, fail_under: float, precision: int) -> bool:
"""Determine if a total should fail due to fail-under.
`total` is a float, the coverage measurement total. `fail_under` is the
fail_under setting to compare with. `precision` is the number of digits
to consider after the decimal point.
Returns True if the total should fail.
"""
# We can never achieve higher than 100% coverage, or less than zero.
if not (0 <= fail_under <= 100.0):
msg = f"fail_under={fail_under} is invalid. Must be between 0 and 100."
raise ConfigError(msg)
# Special case for fail_under=100, it must really be 100.
if fail_under == 100.0 and total != 100.0:
return True
return round(total, precision) < fail_under
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/sqldata.py 0000644 0001751 0001751 00000130726 15073731535 016661 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""SQLite coverage data."""
from __future__ import annotations
import collections
import datetime
import functools
import glob
import itertools
import os
import random
import socket
import sqlite3
import string
import sys
import textwrap
import threading
import uuid
import zlib
from collections.abc import Collection, Mapping, Sequence
from typing import Any, Callable, cast
from coverage.debug import NoDebugging, auto_repr, file_summary
from coverage.exceptions import CoverageException, DataError
from coverage.misc import file_be_gone, isolate_module
from coverage.numbits import numbits_to_nums, numbits_union, nums_to_numbits
from coverage.sqlitedb import SqliteDb
from coverage.types import AnyCallable, FilePath, TArc, TDebugCtl, TLineNo, TWarnFn
from coverage.version import __version__
os = isolate_module(os)
# If you change the schema: increment the SCHEMA_VERSION and update the
# docs in docs/dbschema.rst by running "make cogdoc".
SCHEMA_VERSION = 7
# Schema versions:
# 1: Released in 5.0a2
# 2: Added contexts in 5.0a3.
# 3: Replaced line table with line_map table.
# 4: Changed line_map.bitmap to line_map.numbits.
# 5: Added foreign key declarations.
# 6: Key-value in meta.
# 7: line_map -> line_bits
SCHEMA = """\
CREATE TABLE coverage_schema (
-- One row, to record the version of the schema in this db.
version integer
);
CREATE TABLE meta (
-- Key-value pairs, to record metadata about the data
key text,
value text,
unique (key)
-- Possible keys:
-- 'has_arcs' boolean -- Is this data recording branches?
-- 'sys_argv' text -- The coverage command line that recorded the data.
-- 'version' text -- The version of coverage.py that made the file.
-- 'when' text -- Datetime when the file was created.
);
CREATE TABLE file (
-- A row per file measured.
id integer primary key,
path text,
unique (path)
);
CREATE TABLE context (
-- A row per context measured.
id integer primary key,
context text,
unique (context)
);
CREATE TABLE line_bits (
-- If recording lines, a row per context per file executed.
-- All of the line numbers for that file/context are in one numbits.
file_id integer, -- foreign key to `file`.
context_id integer, -- foreign key to `context`.
numbits blob, -- see the numbits functions in coverage.numbits
foreign key (file_id) references file (id),
foreign key (context_id) references context (id),
unique (file_id, context_id)
);
CREATE TABLE arc (
-- If recording branches, a row per context per from/to line transition executed.
file_id integer, -- foreign key to `file`.
context_id integer, -- foreign key to `context`.
fromno integer, -- line number jumped from.
tono integer, -- line number jumped to.
foreign key (file_id) references file (id),
foreign key (context_id) references context (id),
unique (file_id, context_id, fromno, tono)
);
CREATE TABLE tracer (
-- A row per file indicating the tracer used for that file.
file_id integer primary key,
tracer text,
foreign key (file_id) references file (id)
);
"""
def _locked(method: AnyCallable) -> AnyCallable:
"""A decorator for methods that should hold self._lock."""
@functools.wraps(method)
def _wrapped(self: CoverageData, *args: Any, **kwargs: Any) -> Any:
if self._debug.should("lock"):
self._debug.write(f"Locking {self._lock!r} for {method.__name__}")
with self._lock:
if self._debug.should("lock"):
self._debug.write(f"Locked {self._lock!r} for {method.__name__}")
return method(self, *args, **kwargs)
return _wrapped
class NumbitsUnionAgg:
"""SQLite aggregate function for computing union of numbits."""
def __init__(self) -> None:
self.result = b""
def step(self, value: bytes) -> None:
"""Process one value in the aggregation."""
self.result = numbits_union(self.result, value)
def finalize(self) -> bytes:
"""Return the final aggregated result."""
return self.result
class CoverageData:
"""Manages collected coverage data, including file storage.
This class is the public supported API to the data that coverage.py
collects during program execution. It includes information about what code
was executed. It does not include information from the analysis phase, to
determine what lines could have been executed, or what lines were not
executed.
.. note::
The data file is currently a SQLite database file, with a
:ref:`documented schema `. The schema is subject to change
though, so be careful about querying it directly. Use this API if you
can to isolate yourself from changes.
There are a number of kinds of data that can be collected:
* **lines**: the line numbers of source lines that were executed.
These are always available.
* **arcs**: pairs of source and destination line numbers for transitions
between source lines. These are only available if branch coverage was
used.
* **file tracer names**: the module names of the file tracer plugins that
handled each file in the data.
Lines, arcs, and file tracer names are stored for each source file. File
names in this API are case-sensitive, even on platforms with
case-insensitive file systems.
A data file either stores lines, or arcs, but not both.
A data file is associated with the data when the :class:`CoverageData`
is created, using the parameters `basename`, `suffix`, and `no_disk`. The
base name can be queried with :meth:`base_filename`, and the actual file
name being used is available from :meth:`data_filename`.
To read an existing coverage.py data file, use :meth:`read`. You can then
access the line, arc, or file tracer data with :meth:`lines`, :meth:`arcs`,
or :meth:`file_tracer`.
The :meth:`has_arcs` method indicates whether arc data is available. You
can get a set of the files in the data with :meth:`measured_files`. As
with most Python containers, you can determine if there is any data at all
by using this object as a boolean value.
The contexts for each line in a file can be read with
:meth:`contexts_by_lineno`.
To limit querying to certain contexts, use :meth:`set_query_context` or
:meth:`set_query_contexts`. These will narrow the focus of subsequent
:meth:`lines`, :meth:`arcs`, and :meth:`contexts_by_lineno` calls. The set
of all measured context names can be retrieved with
:meth:`measured_contexts`.
Most data files will be created by coverage.py itself, but you can use
methods here to create data files if you like. The :meth:`add_lines`,
:meth:`add_arcs`, and :meth:`add_file_tracers` methods add data, in ways
that are convenient for coverage.py.
To record data for contexts, use :meth:`set_context` to set a context to
be used for subsequent :meth:`add_lines` and :meth:`add_arcs` calls.
To add a source file without any measured data, use :meth:`touch_file`,
or :meth:`touch_files` for a list of such files.
Write the data to its file with :meth:`write`.
You can clear the data in memory with :meth:`erase`. Data for specific
files can be removed from the database with :meth:`purge_files`.
Two data collections can be combined by using :meth:`update` on one
:class:`CoverageData`, passing it the other.
Data in a :class:`CoverageData` can be serialized and deserialized with
:meth:`dumps` and :meth:`loads`.
The methods used during the coverage.py collection phase
(:meth:`add_lines`, :meth:`add_arcs`, :meth:`set_context`, and
:meth:`add_file_tracers`) are thread-safe. Other methods may not be.
"""
def __init__(
self,
basename: FilePath | None = None,
suffix: str | bool | None = None,
no_disk: bool = False,
warn: TWarnFn | None = None,
debug: TDebugCtl | None = None,
) -> None:
"""Create a :class:`CoverageData` object to hold coverage-measured data.
Arguments:
basename (str): the base name of the data file, defaulting to
".coverage". This can be a path to a file in another directory.
suffix (str or bool): has the same meaning as the `data_suffix`
argument to :class:`coverage.Coverage`.
no_disk (bool): if True, keep all data in memory, and don't
write any disk file.
warn: a warning callback function, accepting a warning message
argument.
debug: a `DebugControl` object (optional)
"""
self._no_disk = no_disk
self._basename = os.path.abspath(basename or ".coverage")
self._suffix = suffix
self._warn = warn
self._debug = debug or NoDebugging()
self._choose_filename()
# Maps filenames to row ids.
self._file_map: dict[str, int] = {}
# Maps thread ids to SqliteDb objects.
self._dbs: dict[int, SqliteDb] = {}
self._pid = os.getpid()
# Synchronize the operations used during collection.
self._lock = threading.RLock()
# Are we in sync with the data file?
self._have_used = False
self._has_lines = False
self._has_arcs = False
self._current_context: str | None = None
self._current_context_id: int | None = None
self._query_context_ids: list[int] | None = None
__repr__ = auto_repr
def _debug_dataio(self, msg: str, filename: str) -> None:
"""A helper for debug messages which are all similar."""
if self._debug.should("dataio"):
self._debug.write(f"{msg} {filename!r} ({file_summary(filename)})")
def _choose_filename(self) -> None:
"""Set self._filename based on inited attributes."""
if self._no_disk:
self._filename = f"file:coverage-{uuid.uuid4()}?mode=memory&cache=shared"
else:
self._filename = self._basename
suffix = filename_suffix(self._suffix)
if suffix:
self._filename += f".{suffix}"
def _reset(self) -> None:
"""Reset our attributes."""
if not self._no_disk:
self.close()
self._file_map = {}
self._have_used = False
self._current_context_id = None
def close(self, force: bool = False) -> None:
"""Really close all the database objects."""
if self._debug.should("dataio"):
self._debug.write(f"Closing dbs, force={force}: {self._dbs}")
for db in self._dbs.values():
db.close(force=force)
self._dbs = {}
def _open_db(self) -> None:
"""Open an existing db file, and read its metadata."""
self._debug_dataio("Opening data file", self._filename)
self._dbs[threading.get_ident()] = SqliteDb(self._filename, self._debug, self._no_disk)
self._read_db()
def _read_db(self) -> None:
"""Read the metadata from a database so that we are ready to use it."""
with self._dbs[threading.get_ident()] as db:
try:
row = db.execute_one("select version from coverage_schema")
assert row is not None
except Exception as exc:
if "no such table: coverage_schema" in str(exc):
self._init_db(db)
else:
raise DataError(
"Data file {!r} doesn't seem to be a coverage data file: {}".format(
self._filename,
exc,
),
) from exc
else:
schema_version = row[0]
if schema_version != SCHEMA_VERSION:
raise DataError(
"Couldn't use data file {!r}: wrong schema: {} instead of {}".format(
self._filename,
schema_version,
SCHEMA_VERSION,
),
)
row = db.execute_one("select value from meta where key = 'has_arcs'")
if row is not None:
self._has_arcs = bool(int(row[0]))
self._has_lines = not self._has_arcs
with db.execute("select id, path from file") as cur:
for file_id, path in cur:
self._file_map[path] = file_id
def _init_db(self, db: SqliteDb) -> None:
"""Write the initial contents of the database."""
self._debug_dataio("Initing data file", self._filename)
db.executescript(SCHEMA)
db.execute_void("INSERT INTO coverage_schema (version) VALUES (?)", (SCHEMA_VERSION,))
# When writing metadata, avoid information that will needlessly change
# the hash of the data file, unless we're debugging processes.
meta_data = [
("version", __version__),
]
if self._debug.should("process"):
meta_data.extend(
[
("sys_argv", str(getattr(sys, "argv", None))),
("when", datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")),
]
)
db.executemany_void("INSERT OR IGNORE INTO meta (key, value) VALUES (?, ?)", meta_data)
def _connect(self) -> SqliteDb:
"""Get the SqliteDb object to use."""
if threading.get_ident() not in self._dbs:
self._open_db()
return self._dbs[threading.get_ident()]
def __bool__(self) -> bool:
if threading.get_ident() not in self._dbs and not os.path.exists(self._filename):
return False
try:
with self._connect() as con:
with con.execute("SELECT * FROM file LIMIT 1") as cur:
return bool(list(cur))
except CoverageException:
return False
def dumps(self) -> bytes:
"""Serialize the current data to a byte string.
The format of the serialized data is not documented. It is only
suitable for use with :meth:`loads` in the same version of
coverage.py.
Note that this serialization is not what gets stored in coverage data
files. This method is meant to produce bytes that can be transmitted
elsewhere and then deserialized with :meth:`loads`.
Returns:
A byte string of serialized data.
.. versionadded:: 5.0
"""
self._debug_dataio("Dumping data from data file", self._filename)
with self._connect() as con:
script = con.dump()
return b"z" + zlib.compress(script.encode("utf-8"))
def loads(self, data: bytes) -> None:
"""Deserialize data from :meth:`dumps`.
Use with a newly-created empty :class:`CoverageData` object. It's
undefined what happens if the object already has data in it.
Note that this is not for reading data from a coverage data file. It
is only for use on data you produced with :meth:`dumps`.
Arguments:
data: A byte string of serialized data produced by :meth:`dumps`.
.. versionadded:: 5.0
"""
self._debug_dataio("Loading data into data file", self._filename)
if data[:1] != b"z":
raise DataError(
f"Unrecognized serialization: {data[:40]!r} (head of {len(data)} bytes)",
)
script = zlib.decompress(data[1:]).decode("utf-8")
self._dbs[threading.get_ident()] = db = SqliteDb(self._filename, self._debug, self._no_disk)
with db:
db.executescript(script)
self._read_db()
self._have_used = True
def _file_id(self, filename: str, add: bool = False) -> int | None:
"""Get the file id for `filename`.
If filename is not in the database yet, add it if `add` is True.
If `add` is not True, return None.
"""
if filename not in self._file_map:
if add:
with self._connect() as con:
self._file_map[filename] = con.execute_for_rowid(
"INSERT OR REPLACE INTO file (path) VALUES (?)",
(filename,),
)
return self._file_map.get(filename)
def _context_id(self, context: str) -> int | None:
"""Get the id for a context."""
assert context is not None
self._start_using()
with self._connect() as con:
row = con.execute_one("SELECT id FROM context WHERE context = ?", (context,))
if row is not None:
return cast(int, row[0])
else:
return None
@_locked
def set_context(self, context: str | None) -> None:
"""Set the current context for future :meth:`add_lines` etc.
`context` is a str, the name of the context to use for the next data
additions. The context persists until the next :meth:`set_context`.
.. versionadded:: 5.0
"""
if self._debug.should("dataop"):
self._debug.write(f"Setting coverage context: {context!r}")
self._current_context = context
self._current_context_id = None
def _set_context_id(self) -> None:
"""Use the _current_context to set _current_context_id."""
context = self._current_context or ""
context_id = self._context_id(context)
if context_id is not None:
self._current_context_id = context_id
else:
with self._connect() as con:
self._current_context_id = con.execute_for_rowid(
"INSERT INTO context (context) VALUES (?)",
(context,),
)
def base_filename(self) -> str:
"""The base filename for storing data.
.. versionadded:: 5.0
"""
return self._basename
def data_filename(self) -> str:
"""Where is the data stored?
.. versionadded:: 5.0
"""
return self._filename
@_locked
def add_lines(self, line_data: Mapping[str, Collection[TLineNo]]) -> None:
"""Add measured line data.
`line_data` is a dictionary mapping file names to iterables of ints::
{ filename: { line1, line2, ... }, ...}
"""
if self._debug.should("dataop"):
self._debug.write(
"Adding lines: %d files, %d lines total"
% (
len(line_data),
sum(len(lines) for lines in line_data.values()),
)
)
if self._debug.should("dataop2"):
for filename, linenos in sorted(line_data.items()):
self._debug.write(f" {filename}: {linenos}")
self._start_using()
self._choose_lines_or_arcs(lines=True)
if not line_data:
return
with self._connect() as con:
self._set_context_id()
for filename, linenos in line_data.items():
line_bits = nums_to_numbits(linenos)
file_id = self._file_id(filename, add=True)
query = "SELECT numbits FROM line_bits WHERE file_id = ? AND context_id = ?"
with con.execute(query, (file_id, self._current_context_id)) as cur:
existing = list(cur)
if existing:
line_bits = numbits_union(line_bits, existing[0][0])
con.execute_void(
"""
INSERT OR REPLACE INTO line_bits
(file_id, context_id, numbits) VALUES (?, ?, ?)
""",
(file_id, self._current_context_id, line_bits),
)
@_locked
def add_arcs(self, arc_data: Mapping[str, Collection[TArc]]) -> None:
"""Add measured arc data.
`arc_data` is a dictionary mapping file names to iterables of pairs of
ints::
{ filename: { (l1,l2), (l1,l2), ... }, ...}
"""
if self._debug.should("dataop"):
self._debug.write(
"Adding arcs: %d files, %d arcs total"
% (
len(arc_data),
sum(len(arcs) for arcs in arc_data.values()),
)
)
if self._debug.should("dataop2"):
for filename, arcs in sorted(arc_data.items()):
self._debug.write(f" {filename}: {arcs}")
self._start_using()
self._choose_lines_or_arcs(arcs=True)
if not arc_data:
return
with self._connect() as con:
self._set_context_id()
for filename, arcs in arc_data.items():
if not arcs:
continue
file_id = self._file_id(filename, add=True)
data = [(file_id, self._current_context_id, fromno, tono) for fromno, tono in arcs]
con.executemany_void(
"""
INSERT OR IGNORE INTO arc
(file_id, context_id, fromno, tono) VALUES (?, ?, ?, ?)
""",
data,
)
def _choose_lines_or_arcs(self, lines: bool = False, arcs: bool = False) -> None:
"""Force the data file to choose between lines and arcs."""
assert lines or arcs
assert not (lines and arcs)
if lines and self._has_arcs:
if self._debug.should("dataop"):
self._debug.write("Error: Can't add line measurements to existing branch data")
raise DataError("Can't add line measurements to existing branch data")
if arcs and self._has_lines:
if self._debug.should("dataop"):
self._debug.write("Error: Can't add branch measurements to existing line data")
raise DataError("Can't add branch measurements to existing line data")
if not self._has_arcs and not self._has_lines:
self._has_lines = lines
self._has_arcs = arcs
with self._connect() as con:
con.execute_void(
"INSERT OR IGNORE INTO meta (key, value) VALUES (?, ?)",
("has_arcs", str(int(arcs))),
)
@_locked
def add_file_tracers(self, file_tracers: Mapping[str, str]) -> None:
"""Add per-file plugin information.
`file_tracers` is { filename: plugin_name, ... }
"""
if self._debug.should("dataop"):
self._debug.write(f"Adding file tracers: {len(file_tracers)} files")
if not file_tracers:
return
self._start_using()
with self._connect() as con:
for filename, plugin_name in file_tracers.items():
file_id = self._file_id(filename, add=True)
existing_plugin = self.file_tracer(filename)
if existing_plugin:
if existing_plugin != plugin_name:
raise DataError(
"Conflicting file tracer name for '{}': {!r} vs {!r}".format(
filename,
existing_plugin,
plugin_name,
),
)
elif plugin_name:
con.execute_void(
"INSERT INTO TRACER (file_id, tracer) VALUES (?, ?)",
(file_id, plugin_name),
)
def touch_file(self, filename: str, plugin_name: str = "") -> None:
"""Ensure that `filename` appears in the data, empty if needed.
`plugin_name` is the name of the plugin responsible for this file.
It is used to associate the right filereporter, etc.
"""
self.touch_files([filename], plugin_name)
def touch_files(self, filenames: Collection[str], plugin_name: str | None = None) -> None:
"""Ensure that `filenames` appear in the data, empty if needed.
`plugin_name` is the name of the plugin responsible for these files.
It is used to associate the right filereporter, etc.
"""
if self._debug.should("dataop"):
self._debug.write(f"Touching {filenames!r}")
self._start_using()
with self._connect(): # Use this to get one transaction.
if not self._has_arcs and not self._has_lines:
raise DataError("Can't touch files in an empty CoverageData")
for filename in filenames:
self._file_id(filename, add=True)
if plugin_name:
# Set the tracer for this file
self.add_file_tracers({filename: plugin_name})
def purge_files(self, filenames: Collection[str]) -> None:
"""Purge any existing coverage data for the given `filenames`.
.. versionadded:: 7.2
"""
if self._debug.should("dataop"):
self._debug.write(f"Purging data for {filenames!r}")
self._start_using()
with self._connect() as con:
if self._has_lines:
sql = "DELETE FROM line_bits WHERE file_id=?"
elif self._has_arcs:
sql = "DELETE FROM arc WHERE file_id=?"
else:
raise DataError("Can't purge files in an empty CoverageData")
for filename in filenames:
file_id = self._file_id(filename, add=False)
if file_id is None:
continue
con.execute_void(sql, (file_id,))
def update(
self,
other_data: CoverageData,
map_path: Callable[[str], str] | None = None,
) -> None:
"""Update this data with data from another :class:`CoverageData`.
If `map_path` is provided, it's a function that re-map paths to match
the local machine's. Note: `map_path` is None only when called
directly from the test suite.
"""
if self._debug.should("dataop"):
self._debug.write(
"Updating with data from {!r}".format(
getattr(other_data, "_filename", "???"),
)
)
if self._has_lines and other_data._has_arcs:
raise DataError(
"Can't combine branch coverage data with statement data", slug="cant-combine"
)
if self._has_arcs and other_data._has_lines:
raise DataError(
"Can't combine statement coverage data with branch data", slug="cant-combine"
)
map_path = map_path or (lambda p: p)
# Force the database we're writing to to exist before we start nesting contexts.
self._start_using()
other_data.read()
# Ensure other_data has a properly initialized database
with other_data._connect():
pass
with self._connect() as con:
assert con.con is not None
con.con.isolation_level = "IMMEDIATE"
# Register functions for SQLite
con.con.create_function("numbits_union", 2, numbits_union)
con.con.create_function("map_path", 1, map_path)
con.con.create_aggregate(
"numbits_union_agg",
1,
NumbitsUnionAgg, # type: ignore[arg-type]
)
# Attach the other database
con.execute_void("ATTACH DATABASE ? AS other_db", (other_data.data_filename(),))
# Create temporary table with mapped file paths to avoid repeated map_path() calls
con.execute_void("""
CREATE TEMP TABLE other_file_mapped AS
SELECT
other_file.id as other_file_id,
map_path(other_file.path) as mapped_path
FROM other_db.file AS other_file
""")
# Check for tracer conflicts before proceeding
with con.execute("""
SELECT other_file_mapped.mapped_path,
COALESCE(main.tracer.tracer, ''),
COALESCE(other_db.tracer.tracer, '')
FROM main.file
LEFT JOIN main.tracer ON main.file.id = main.tracer.file_id
INNER JOIN other_file_mapped ON main.file.path = other_file_mapped.mapped_path
LEFT JOIN other_db.tracer ON other_file_mapped.other_file_id = other_db.tracer.file_id
WHERE COALESCE(main.tracer.tracer, '') != COALESCE(other_db.tracer.tracer, '')
""") as cur:
conflicts = list(cur)
if conflicts:
path, this_tracer, other_tracer = conflicts[0]
raise DataError(
"Conflicting file tracer name for '{}': {!r} vs {!r}".format(
path,
this_tracer,
other_tracer,
),
)
# Insert missing files from other_db (with map_path applied)
con.execute_void("""
INSERT OR IGNORE INTO main.file (path)
SELECT DISTINCT mapped_path FROM other_file_mapped
""")
# Insert missing contexts from other_db
con.execute_void("""
INSERT OR IGNORE INTO main.context (context)
SELECT context FROM other_db.context
""")
# Update file_map with any new files
with con.execute("SELECT id, path FROM file") as cur:
self._file_map.update({path: id for id, path in cur})
with con.execute("""
SELECT
EXISTS(SELECT 1 FROM other_db.arc),
EXISTS(SELECT 1 FROM other_db.line_bits)
""") as cur:
has_arcs, has_lines = cur.fetchone()
# Handle arcs if present in other_db
if has_arcs:
self._choose_lines_or_arcs(arcs=True)
# Create context mapping table for faster lookups
con.execute_void("""
CREATE TEMP TABLE context_mapping AS
SELECT
other_context.id as other_id,
main_context.id as main_id
FROM other_db.context AS other_context
INNER JOIN main.context AS main_context ON other_context.context = main_context.context
""")
con.execute_void("""
INSERT OR IGNORE INTO main.arc (file_id, context_id, fromno, tono)
SELECT
main_file.id,
context_mapping.main_id,
other_arc.fromno,
other_arc.tono
FROM other_db.arc AS other_arc
INNER JOIN other_file_mapped ON other_arc.file_id = other_file_mapped.other_file_id
INNER JOIN context_mapping ON other_arc.context_id = context_mapping.other_id
INNER JOIN main.file AS main_file ON other_file_mapped.mapped_path = main_file.path
""")
# Handle line_bits if present in other_db
if has_lines:
self._choose_lines_or_arcs(lines=True)
# Handle line_bits by aggregating other_db data by mapped target,
# then inserting/updating
con.execute_void("""
INSERT OR REPLACE INTO main.line_bits (file_id, context_id, numbits)
SELECT
main_file.id,
main_context.id,
numbits_union(
COALESCE((
SELECT numbits FROM main.line_bits
WHERE file_id = main_file.id AND context_id = main_context.id
), X''),
aggregated.combined_numbits
)
FROM (
SELECT
other_file_mapped.mapped_path,
other_context.context,
numbits_union_agg(other_line_bits.numbits) as combined_numbits
FROM other_db.line_bits AS other_line_bits
INNER JOIN other_file_mapped ON other_line_bits.file_id = other_file_mapped.other_file_id
INNER JOIN other_db.context AS other_context ON other_line_bits.context_id = other_context.id
GROUP BY other_file_mapped.mapped_path, other_context.context
) AS aggregated
INNER JOIN main.file AS main_file ON aggregated.mapped_path = main_file.path
INNER JOIN main.context AS main_context ON aggregated.context = main_context.context
""")
# Insert tracers from other_db (avoiding conflicts we already checked)
con.execute_void("""
INSERT OR IGNORE INTO main.tracer (file_id, tracer)
SELECT
main_file.id,
other_tracer.tracer
FROM other_db.tracer AS other_tracer
INNER JOIN other_file_mapped ON other_tracer.file_id = other_file_mapped.other_file_id
INNER JOIN main.file AS main_file ON other_file_mapped.mapped_path = main_file.path
""")
if not self._no_disk:
# Update all internal cache data.
self._reset()
self.read()
def erase(self, parallel: bool = False) -> None:
"""Erase the data in this object.
If `parallel` is true, then also deletes data files created from the
basename by parallel-mode.
"""
self._reset()
if self._no_disk:
return
self._debug_dataio("Erasing data file", self._filename)
file_be_gone(self._filename)
if parallel:
data_dir, local = os.path.split(self._filename)
local_abs_path = os.path.join(os.path.abspath(data_dir), local)
pattern = glob.escape(local_abs_path) + ".*"
for filename in glob.glob(pattern):
self._debug_dataio("Erasing parallel data file", filename)
file_be_gone(filename)
def read(self) -> None:
"""Start using an existing data file."""
if os.path.exists(self._filename):
with self._connect():
self._have_used = True
def write(self) -> None:
"""Ensure the data is written to the data file."""
self._debug_dataio("Writing (no-op) data file", self._filename)
def _start_using(self) -> None:
"""Call this before using the database at all."""
if self._pid != os.getpid():
# Looks like we forked! Have to start a new data file.
self._reset()
self._choose_filename()
self._pid = os.getpid()
if not self._have_used:
self.erase()
self._have_used = True
def has_arcs(self) -> bool:
"""Does the database have arcs (True) or lines (False)."""
return bool(self._has_arcs)
def measured_files(self) -> set[str]:
"""A set of all files that have been measured.
Note that a file may be mentioned as measured even though no lines or
arcs for that file are present in the data.
"""
return set(self._file_map)
def measured_contexts(self) -> set[str]:
"""A set of all contexts that have been measured.
.. versionadded:: 5.0
"""
self._start_using()
with self._connect() as con:
with con.execute("SELECT DISTINCT(context) FROM context") as cur:
contexts = {row[0] for row in cur}
return contexts
def file_tracer(self, filename: str) -> str | None:
"""Get the plugin name of the file tracer for a file.
Returns the name of the plugin that handles this file. If the file was
measured, but didn't use a plugin, then "" is returned. If the file
was not measured, then None is returned.
"""
self._start_using()
with self._connect() as con:
file_id = self._file_id(filename)
if file_id is None:
return None
row = con.execute_one("SELECT tracer FROM tracer WHERE file_id = ?", (file_id,))
if row is not None:
return row[0] or ""
return "" # File was measured, but no tracer associated.
def set_query_context(self, context: str) -> None:
"""Set a context for subsequent querying.
The next :meth:`lines`, :meth:`arcs`, or :meth:`contexts_by_lineno`
calls will be limited to only one context. `context` is a string which
must match a context exactly. If it does not, no exception is raised,
but queries will return no data.
.. versionadded:: 5.0
"""
self._start_using()
with self._connect() as con:
with con.execute("SELECT id FROM context WHERE context = ?", (context,)) as cur:
self._query_context_ids = [row[0] for row in cur.fetchall()]
def set_query_contexts(self, contexts: Sequence[str] | None) -> None:
"""Set a number of contexts for subsequent querying.
The next :meth:`lines`, :meth:`arcs`, or :meth:`contexts_by_lineno`
calls will be limited to the specified contexts. `contexts` is a list
of Python regular expressions. Contexts will be matched using
:func:`re.search `. Data will be included in query
results if they are part of any of the contexts matched.
.. versionadded:: 5.0
"""
self._start_using()
if contexts:
with self._connect() as con:
context_clause = " or ".join(["context REGEXP ?"] * len(contexts))
with con.execute("SELECT id FROM context WHERE " + context_clause, contexts) as cur:
self._query_context_ids = [row[0] for row in cur.fetchall()]
else:
self._query_context_ids = None
def lines(self, filename: str) -> list[TLineNo] | None:
"""Get the list of lines executed for a source file.
If the file was not measured, returns None. A file might be measured,
and have no lines executed, in which case an empty list is returned.
If the file was executed, returns a list of integers, the line numbers
executed in the file. The list is in no particular order.
"""
self._start_using()
if self.has_arcs():
arcs = self.arcs(filename)
if arcs is not None:
all_lines = itertools.chain.from_iterable(arcs)
return list({l for l in all_lines if l > 0})
with self._connect() as con:
file_id = self._file_id(filename)
if file_id is None:
return None
else:
query = "SELECT numbits FROM line_bits WHERE file_id = ?"
data = [file_id]
if self._query_context_ids is not None:
ids_array = ", ".join("?" * len(self._query_context_ids))
query += " AND context_id IN (" + ids_array + ")"
data += self._query_context_ids
with con.execute(query, data) as cur:
bitmaps = list(cur)
nums = set()
for row in bitmaps:
nums.update(numbits_to_nums(row[0]))
return list(nums)
def arcs(self, filename: str) -> list[TArc] | None:
"""Get the list of arcs executed for a file.
If the file was not measured, returns None. A file might be measured,
and have no arcs executed, in which case an empty list is returned.
If the file was executed, returns a list of 2-tuples of integers. Each
pair is a starting line number and an ending line number for a
transition from one line to another. The list is in no particular
order.
Negative numbers have special meaning. If the starting line number is
-N, it represents an entry to the code object that starts at line N.
If the ending ling number is -N, it's an exit from the code object that
starts at line N.
"""
self._start_using()
with self._connect() as con:
file_id = self._file_id(filename)
if file_id is None:
return None
else:
query = "SELECT DISTINCT fromno, tono FROM arc WHERE file_id = ?"
data = [file_id]
if self._query_context_ids is not None:
ids_array = ", ".join("?" * len(self._query_context_ids))
query += " AND context_id IN (" + ids_array + ")"
data += self._query_context_ids
with con.execute(query, data) as cur:
return list(cur)
def contexts_by_lineno(self, filename: str) -> dict[TLineNo, list[str]]:
"""Get the contexts for each line in a file.
Returns:
A dict mapping line numbers to a list of context names.
.. versionadded:: 5.0
"""
self._start_using()
with self._connect() as con:
file_id = self._file_id(filename)
if file_id is None:
return {}
lineno_contexts_map = collections.defaultdict(set)
if self.has_arcs():
query = """
SELECT arc.fromno, arc.tono, context.context
FROM arc, context
WHERE arc.file_id = ? AND arc.context_id = context.id
"""
data = [file_id]
if self._query_context_ids is not None:
ids_array = ", ".join("?" * len(self._query_context_ids))
query += " AND arc.context_id IN (" + ids_array + ")"
data += self._query_context_ids
with con.execute(query, data) as cur:
for fromno, tono, context in cur:
if fromno > 0:
lineno_contexts_map[fromno].add(context)
if tono > 0:
lineno_contexts_map[tono].add(context)
else:
query = """
SELECT l.numbits, c.context FROM line_bits l, context c
WHERE l.context_id = c.id
AND file_id = ?
"""
data = [file_id]
if self._query_context_ids is not None:
ids_array = ", ".join("?" * len(self._query_context_ids))
query += " AND l.context_id IN (" + ids_array + ")"
data += self._query_context_ids
with con.execute(query, data) as cur:
for numbits, context in cur:
for lineno in numbits_to_nums(numbits):
lineno_contexts_map[lineno].add(context)
return {lineno: list(contexts) for lineno, contexts in lineno_contexts_map.items()}
@classmethod
def sys_info(cls) -> list[tuple[str, Any]]:
"""Our information for `Coverage.sys_info`.
Returns a list of (key, value) pairs.
"""
with SqliteDb(":memory:", debug=NoDebugging()) as db:
with db.execute("PRAGMA temp_store") as cur:
temp_store = [row[0] for row in cur]
with db.execute("PRAGMA compile_options") as cur:
copts = [row[0] for row in cur]
copts = textwrap.wrap(", ".join(copts), width=75)
return [
("sqlite3_sqlite_version", sqlite3.sqlite_version),
("sqlite3_temp_store", temp_store),
("sqlite3_compile_options", copts),
]
def filename_suffix(suffix: str | bool | None) -> str | None:
"""Compute a filename suffix for a data file.
If `suffix` is a string or None, simply return it. If `suffix` is True,
then build a suffix incorporating the hostname, process id, and a random
number.
Returns a string or None.
"""
if suffix is True:
# If data_suffix was a simple true value, then make a suffix with
# plenty of distinguishing information. We do this here in
# `save()` at the last minute so that the pid will be correct even
# if the process forks.
die = random.Random(os.urandom(8))
letters = string.ascii_uppercase + string.ascii_lowercase
rolls = "".join(die.choice(letters) for _ in range(6))
suffix = f"{socket.gethostname()}.{os.getpid()}.X{rolls}x"
elif suffix is False:
suffix = None
return suffix
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/sqlitedb.py 0000644 0001751 0001751 00000023432 15073731535 017032 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""SQLite abstraction for coverage.py"""
from __future__ import annotations
import contextlib
import re
import sqlite3
from collections.abc import Iterable, Iterator
from typing import Any, cast
from coverage.debug import auto_repr, clipped_repr, exc_one_line
from coverage.exceptions import DataError
from coverage.types import TDebugCtl
class SqliteDb:
"""A simple abstraction over a SQLite database.
Use as a context manager, then you can use it like a
:class:`python:sqlite3.Connection` object::
with SqliteDb(filename, debug_control) as db:
with db.execute("select a, b from some_table") as cur:
for a, b in cur:
etc(a, b)
"""
def __init__(self, filename: str, debug: TDebugCtl, no_disk: bool = False) -> None:
self.debug = debug
self.filename = filename
self.no_disk = no_disk
self.nest = 0
self.con: sqlite3.Connection | None = None
__repr__ = auto_repr
def _connect(self) -> None:
"""Connect to the db and do universal initialization."""
if self.con is not None:
return
# It can happen that Python switches threads while the tracer writes
# data. The second thread will also try to write to the data,
# effectively causing a nested context. However, given the idempotent
# nature of the tracer operations, sharing a connection among threads
# is not a problem.
if self.debug.should("sql"):
self.debug.write(f"Connecting to {self.filename!r}")
try:
# Use uri=True when connecting to memory URIs
if self.filename.startswith("file:"):
self.con = sqlite3.connect(self.filename, check_same_thread=False, uri=True)
else:
self.con = sqlite3.connect(self.filename, check_same_thread=False)
except sqlite3.Error as exc:
raise DataError(f"Couldn't use data file {self.filename!r}: {exc}") from exc
if self.debug.should("sql"):
self.debug.write(f"Connected to {self.filename!r} as {self.con!r}")
self.con.create_function("REGEXP", 2, lambda txt, pat: re.search(txt, pat) is not None)
# Turning off journal_mode can speed up writing. It can't always be
# disabled, so we have to be prepared for *-journal files elsewhere.
# In Python 3.12+, we can change the config to allow journal_mode=off.
if hasattr(sqlite3, "SQLITE_DBCONFIG_DEFENSIVE"):
# Turn off defensive mode, so that journal_mode=off can succeed.
self.con.setconfig( # type: ignore[attr-defined, unused-ignore]
sqlite3.SQLITE_DBCONFIG_DEFENSIVE,
False,
)
# This pragma makes writing faster. It disables rollbacks, but we never need them.
self.execute_void("pragma journal_mode=off")
# This pragma makes writing faster. It can fail in unusual situations
# (https://github.com/nedbat/coveragepy/issues/1646), so use fail_ok=True
# to keep things going.
self.execute_void("pragma synchronous=off", fail_ok=True)
def close(self, force: bool = False) -> None:
"""If needed, close the connection."""
if self.con is not None:
if force or not self.no_disk:
if self.debug.should("sql"):
self.debug.write(f"Closing {self.con!r} on {self.filename!r}")
self.con.close()
self.con = None
def __enter__(self) -> SqliteDb:
if self.nest == 0:
self._connect()
assert self.con is not None
self.con.__enter__()
self.nest += 1
return self
def __exit__(self, exc_type, exc_value, traceback) -> None: # type: ignore[no-untyped-def]
self.nest -= 1
if self.nest == 0:
try:
assert self.con is not None
self.con.__exit__(exc_type, exc_value, traceback)
self.close()
except Exception as exc:
if self.debug.should("sql"):
self.debug.write(f"EXCEPTION from __exit__: {exc_one_line(exc)}")
raise DataError(f"Couldn't end data file {self.filename!r}: {exc}") from exc
def _execute(self, sql: str, parameters: Iterable[Any]) -> sqlite3.Cursor:
"""Same as :meth:`python:sqlite3.Connection.execute`."""
if self.debug.should("sql"):
tail = f" with {parameters!r}" if parameters else ""
self.debug.write(f"Executing {sql!r}{tail}")
try:
assert self.con is not None
try:
return self.con.execute(sql, parameters) # type: ignore[arg-type]
except Exception:
# In some cases, an error might happen that isn't really an
# error. Try again immediately.
# https://github.com/nedbat/coveragepy/issues/1010
return self.con.execute(sql, parameters) # type: ignore[arg-type]
except sqlite3.Error as exc:
msg = str(exc)
if not self.no_disk:
try:
# `execute` is the first thing we do with the database, so try
# hard to provide useful hints if something goes wrong now.
with open(self.filename, "rb") as bad_file:
cov4_sig = b"!coverage.py: This is a private format"
if bad_file.read(len(cov4_sig)) == cov4_sig:
msg = (
"Looks like a coverage 4.x data file. "
+ "Are you mixing versions of coverage?"
)
except Exception:
pass
if self.debug.should("sql"):
self.debug.write(f"EXCEPTION from execute: {exc_one_line(exc)}")
raise DataError(f"Couldn't use data file {self.filename!r}: {msg}") from exc
@contextlib.contextmanager
def execute(
self,
sql: str,
parameters: Iterable[Any] = (),
) -> Iterator[sqlite3.Cursor]:
"""Context managed :meth:`python:sqlite3.Connection.execute`.
Use with a ``with`` statement to auto-close the returned cursor.
"""
cur = self._execute(sql, parameters)
try:
yield cur
finally:
cur.close()
def execute_void(self, sql: str, parameters: Iterable[Any] = (), fail_ok: bool = False) -> None:
"""Same as :meth:`python:sqlite3.Connection.execute` when you don't need the cursor.
If `fail_ok` is True, then SQLite errors are ignored.
"""
try:
# PyPy needs the .close() calls here, or sqlite gets twisted up:
# https://bitbucket.org/pypy/pypy/issues/2872/default-isolation-mode-is-different-on
self._execute(sql, parameters).close()
except DataError:
if not fail_ok:
raise
def execute_for_rowid(self, sql: str, parameters: Iterable[Any] = ()) -> int:
"""Like execute, but returns the lastrowid."""
with self.execute(sql, parameters) as cur:
assert cur.lastrowid is not None
rowid: int = cur.lastrowid
if self.debug.should("sqldata"):
self.debug.write(f"Row id result: {rowid!r}")
return rowid
def execute_one(self, sql: str, parameters: Iterable[Any] = ()) -> tuple[Any, ...] | None:
"""Execute a statement and return the one row that results.
This is like execute(sql, parameters).fetchone(), except it is
correct in reading the entire result set. This will raise an
exception if more than one row results.
Returns a row, or None if there were no rows.
"""
with self.execute(sql, parameters) as cur:
rows = list(cur)
if len(rows) == 0:
return None
elif len(rows) == 1:
return cast(tuple[Any, ...], rows[0])
else:
raise AssertionError(f"SQL {sql!r} shouldn't return {len(rows)} rows")
def _executemany(self, sql: str, data: list[Any]) -> sqlite3.Cursor:
"""Same as :meth:`python:sqlite3.Connection.executemany`."""
if self.debug.should("sql"):
final = ":" if self.debug.should("sqldata") else ""
self.debug.write(f"Executing many {sql!r} with {len(data)} rows{final}")
if self.debug.should("sqldata"):
for i, row in enumerate(data):
self.debug.write(f"{i:4d}: {row!r}")
assert self.con is not None
try:
return self.con.executemany(sql, data)
except Exception:
# In some cases, an error might happen that isn't really an
# error. Try again immediately.
# https://github.com/nedbat/coveragepy/issues/1010
return self.con.executemany(sql, data)
def executemany_void(self, sql: str, data: list[Any]) -> None:
"""Same as :meth:`python:sqlite3.Connection.executemany` when you don't need the cursor."""
self._executemany(sql, data).close()
def executescript(self, script: str) -> None:
"""Same as :meth:`python:sqlite3.Connection.executescript`."""
if self.debug.should("sql"):
self.debug.write(
"Executing script with {} chars: {}".format(
len(script),
clipped_repr(script, 100),
)
)
assert self.con is not None
self.con.executescript(script).close()
def dump(self) -> str:
"""Return a multi-line string, the SQL dump of the database."""
assert self.con is not None
return "\n".join(self.con.iterdump())
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/sysmon.py 0000644 0001751 0001751 00000042140 15073731535 016550 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Callback functions and support for sys.monitoring data collection."""
from __future__ import annotations
import functools
import inspect
import os
import os.path
import sys
import threading
import traceback
from dataclasses import dataclass
from types import CodeType
from typing import Any, Callable, NewType, Optional, cast
from coverage import env
from coverage.bytecode import TBranchTrails, always_jumps, branch_trails
from coverage.debug import short_filename, short_stack
from coverage.misc import isolate_module
from coverage.types import (
AnyCallable,
TFileDisposition,
TLineNo,
TOffset,
Tracer,
TShouldStartContextFn,
TShouldTraceFn,
TTraceData,
TTraceFileData,
TWarnFn,
)
os = isolate_module(os)
# pylint: disable=unused-argument
# $set_env.py: COVERAGE_SYSMON_LOG - Log sys.monitoring activity
LOG = bool(int(os.getenv("COVERAGE_SYSMON_LOG", 0)))
# $set_env.py: COVERAGE_SYSMON_STATS - Collect sys.monitoring stats
COLLECT_STATS = bool(int(os.getenv("COVERAGE_SYSMON_STATS", 0)))
# This module will be imported in all versions of Python, but only used in 3.12+
# It will be type-checked for 3.12, but not for earlier versions.
sys_monitoring = getattr(sys, "monitoring", None)
DISABLE_TYPE = NewType("DISABLE_TYPE", object)
MonitorReturn = Optional[DISABLE_TYPE]
DISABLE = cast(MonitorReturn, getattr(sys_monitoring, "DISABLE", None))
if LOG: # pragma: debugging
class LoggingWrapper:
"""Wrap a namespace to log all its functions."""
def __init__(self, wrapped: Any, namespace: str) -> None:
self.wrapped = wrapped
self.namespace = namespace
def __getattr__(self, name: str) -> Callable[..., Any]:
def _wrapped(*args: Any, **kwargs: Any) -> Any:
log(f"{self.namespace}.{name}{args}{kwargs}")
return getattr(self.wrapped, name)(*args, **kwargs)
return _wrapped
sys_monitoring = LoggingWrapper(sys_monitoring, "sys.monitoring")
assert sys_monitoring is not None
short_stack = functools.partial(
short_stack,
full=True,
short_filenames=True,
frame_ids=True,
)
seen_threads: set[int] = set()
def log(msg: str) -> None:
"""Write a message to our detailed debugging log(s)."""
# Thread ids are reused across processes?
# Make a shorter number more likely to be unique.
pid = os.getpid()
tid = cast(int, threading.current_thread().ident)
tslug = f"{(pid * tid) % 9_999_991:07d}"
if tid not in seen_threads:
seen_threads.add(tid)
log(f"New thread {tid} {tslug}:\n{short_stack()}")
# log_seq = int(os.getenv("PANSEQ", "0"))
# root = f"/tmp/pan.{log_seq:03d}"
for filename in [
"/tmp/foo.out",
# f"{root}.out",
# f"{root}-{pid}.out",
# f"{root}-{pid}-{tslug}.out",
]:
with open(filename, "a", encoding="utf-8") as f:
try:
print(f"{pid}:{tslug}: {msg}", file=f, flush=True)
except UnicodeError:
print(f"{pid}:{tslug}: {ascii(msg)}", file=f, flush=True)
def arg_repr(arg: Any) -> str:
"""Make a customized repr for logged values."""
if isinstance(arg, CodeType):
return (
f""
)
return repr(arg)
def panopticon(*names: str | None) -> AnyCallable:
"""Decorate a function to log its calls."""
def _decorator(method: AnyCallable) -> AnyCallable:
@functools.wraps(method)
def _wrapped(self: Any, *args: Any) -> Any:
try:
# log(f"{method.__name__}() stack:\n{short_stack()}")
args_reprs = []
for name, arg in zip(names, args):
if name is None:
continue
args_reprs.append(f"{name}={arg_repr(arg)}")
log(f"{id(self):#x}:{method.__name__}({', '.join(args_reprs)})")
ret = method(self, *args)
# log(f" end {id(self):#x}:{method.__name__}({', '.join(args_reprs)})")
return ret
except Exception as exc:
log(f"!!{exc.__class__.__name__}: {exc}")
if 1:
log("".join(traceback.format_exception(exc)))
try:
assert sys_monitoring is not None
sys_monitoring.set_events(sys.monitoring.COVERAGE_ID, 0)
except ValueError:
# We might have already shut off monitoring.
log("oops, shutting off events with disabled tool id")
raise
return _wrapped
return _decorator
else:
def log(msg: str) -> None:
"""Write a message to our detailed debugging log(s), but not really."""
def panopticon(*names: str | None) -> AnyCallable:
"""Decorate a function to log its calls, but not really."""
def _decorator(meth: AnyCallable) -> AnyCallable:
return meth
return _decorator
@dataclass
class CodeInfo:
"""The information we want about each code object."""
tracing: bool
file_data: TTraceFileData | None
byte_to_line: dict[TOffset, TLineNo] | None
# Keys are start instruction offsets for branches.
# Values are dicts:
# {
# (from_line, to_line): {offset, offset, ...},
# (from_line, to_line): {offset, offset, ...},
# }
branch_trails: TBranchTrails
# Always-jumps are bytecode offsets that do no work but move
# to another offset.
always_jumps: dict[TOffset, TOffset]
def bytes_to_lines(code: CodeType) -> dict[TOffset, TLineNo]:
"""Make a dict mapping byte code offsets to line numbers."""
b2l = {}
for bstart, bend, lineno in code.co_lines():
if lineno is not None:
for boffset in range(bstart, bend, 2):
b2l[boffset] = lineno
return b2l
class SysMonitor(Tracer):
"""Python implementation of the raw data tracer for PEP669 implementations."""
# One of these will be used across threads. Be careful.
def __init__(self, tool_id: int) -> None:
# Attributes set from the collector:
self.data: TTraceData
self.trace_arcs = False
self.should_trace: TShouldTraceFn
self.should_trace_cache: dict[str, TFileDisposition | None]
# TODO: should_start_context and switch_context are unused!
# Change tests/testenv.py:DYN_CONTEXTS when this is updated.
self.should_start_context: TShouldStartContextFn | None = None
self.switch_context: Callable[[str | None], None] | None = None
self.lock_data: Callable[[], None]
self.unlock_data: Callable[[], None]
# TODO: warn is unused.
self.warn: TWarnFn
self.myid = tool_id
# Map id(code_object) -> CodeInfo
self.code_infos: dict[int, CodeInfo] = {}
# A list of code_objects, just to keep them alive so that id's are
# useful as identity.
self.code_objects: list[CodeType] = []
self.sysmon_on = False
self.lock = threading.Lock()
self.stats: dict[str, int] | None = None
if COLLECT_STATS:
self.stats = dict.fromkeys(
"starts start_tracing returns line_lines line_arcs branches branch_trails".split(),
0,
)
self._activity = False
def __repr__(self) -> str:
points = sum(len(v) for v in self.data.values())
files = len(self.data)
return f""
@panopticon()
def start(self) -> None:
"""Start this Tracer."""
with self.lock:
assert sys_monitoring is not None
sys_monitoring.use_tool_id(self.myid, "coverage.py")
register = functools.partial(sys_monitoring.register_callback, self.myid)
events = sys.monitoring.events
sys_monitoring.set_events(self.myid, events.PY_START)
register(events.PY_START, self.sysmon_py_start)
if self.trace_arcs:
register(events.PY_RETURN, self.sysmon_py_return)
register(events.LINE, self.sysmon_line_arcs)
if env.PYBEHAVIOR.branch_right_left:
register(
events.BRANCH_RIGHT, # type:ignore[attr-defined]
self.sysmon_branch_either,
)
register(
events.BRANCH_LEFT, # type:ignore[attr-defined]
self.sysmon_branch_either,
)
else:
register(events.LINE, self.sysmon_line_lines)
sys_monitoring.restart_events()
self.sysmon_on = True
@panopticon()
def stop(self) -> None:
"""Stop this Tracer."""
with self.lock:
if not self.sysmon_on:
# In forking situations, we might try to stop when we are not
# started. Do nothing in that case.
return
assert sys_monitoring is not None
sys_monitoring.set_events(self.myid, 0)
self.sysmon_on = False
sys_monitoring.free_tool_id(self.myid)
@panopticon()
def post_fork(self) -> None:
"""The process has forked, clean up as needed."""
self.stop()
def activity(self) -> bool:
"""Has there been any activity?"""
return self._activity
def reset_activity(self) -> None:
"""Reset the activity() flag."""
self._activity = False
def get_stats(self) -> dict[str, int] | None:
"""Return a dictionary of statistics, or None."""
return self.stats
@panopticon("code", "@")
def sysmon_py_start(self, code: CodeType, instruction_offset: TOffset) -> MonitorReturn:
"""Handle sys.monitoring.events.PY_START events."""
# Entering a new frame. Decide if we should trace in this file.
self._activity = True
if self.stats is not None:
self.stats["starts"] += 1
code_info = self.code_infos.get(id(code))
tracing_code: bool | None = None
file_data: TTraceFileData | None = None
if code_info is not None:
tracing_code = code_info.tracing
file_data = code_info.file_data
if tracing_code is None:
filename = code.co_filename
disp = self.should_trace_cache.get(filename)
if disp is None:
frame = inspect.currentframe()
if frame is not None:
frame = inspect.currentframe().f_back # type: ignore[union-attr]
if LOG:
# @panopticon adds a frame.
frame = frame.f_back # type: ignore[union-attr]
disp = self.should_trace(filename, frame) # type: ignore[arg-type]
self.should_trace_cache[filename] = disp
tracing_code = disp.trace
if tracing_code:
tracename = disp.source_filename
assert tracename is not None
self.lock_data()
try:
if tracename not in self.data:
self.data[tracename] = set()
finally:
self.unlock_data()
file_data = self.data[tracename]
b2l = bytes_to_lines(code)
else:
file_data = None
b2l = None
code_info = CodeInfo(
tracing=tracing_code,
file_data=file_data,
byte_to_line=b2l,
branch_trails={},
always_jumps={},
)
self.code_infos[id(code)] = code_info
self.code_objects.append(code)
if tracing_code:
if self.stats is not None:
self.stats["start_tracing"] += 1
events = sys.monitoring.events
with self.lock:
if self.sysmon_on:
assert sys_monitoring is not None
local_events = events.PY_RETURN | events.PY_RESUME | events.LINE
if self.trace_arcs:
assert env.PYBEHAVIOR.branch_right_left
local_events |= (
events.BRANCH_RIGHT # type:ignore[attr-defined]
| events.BRANCH_LEFT # type:ignore[attr-defined]
)
sys_monitoring.set_local_events(self.myid, code, local_events)
return DISABLE
@panopticon("code", "@", None)
def sysmon_py_return(
self,
code: CodeType,
instruction_offset: TOffset,
retval: object,
) -> MonitorReturn:
"""Handle sys.monitoring.events.PY_RETURN events for branch coverage."""
if self.stats is not None:
self.stats["returns"] += 1
code_info = self.code_infos.get(id(code))
# code_info is not None and code_info.file_data is not None, since we
# wouldn't have enabled this event if they were.
last_line = code_info.byte_to_line[instruction_offset] # type: ignore
if last_line is not None:
arc = (last_line, -code.co_firstlineno)
code_info.file_data.add(arc) # type: ignore
# log(f"adding {arc=}")
return DISABLE
@panopticon("code", "line")
def sysmon_line_lines(self, code: CodeType, line_number: TLineNo) -> MonitorReturn:
"""Handle sys.monitoring.events.LINE events for line coverage."""
if self.stats is not None:
self.stats["line_lines"] += 1
code_info = self.code_infos.get(id(code))
# It should be true that code_info is not None and code_info.file_data
# is not None, since we wouldn't have enabled this event if they were.
# But somehow code_info can be None here, so we have to check.
if code_info is not None and code_info.file_data is not None:
code_info.file_data.add(line_number) # type: ignore
# log(f"adding {line_number=}")
return DISABLE
@panopticon("code", "line")
def sysmon_line_arcs(self, code: CodeType, line_number: TLineNo) -> MonitorReturn:
"""Handle sys.monitoring.events.LINE events for branch coverage."""
if self.stats is not None:
self.stats["line_arcs"] += 1
code_info = self.code_infos[id(code)]
# code_info is not None and code_info.file_data is not None, since we
# wouldn't have enabled this event if they were.
arc = (line_number, line_number)
code_info.file_data.add(arc) # type: ignore
# log(f"adding {arc=}")
return DISABLE
@panopticon("code", "@", "@")
def sysmon_branch_either(
self, code: CodeType, instruction_offset: TOffset, destination_offset: TOffset
) -> MonitorReturn:
"""Handle BRANCH_RIGHT and BRANCH_LEFT events."""
if self.stats is not None:
self.stats["branches"] += 1
code_info = self.code_infos[id(code)]
# code_info is not None and code_info.file_data is not None, since we
# wouldn't have enabled this event if they were.
if not code_info.branch_trails:
if self.stats is not None:
self.stats["branch_trails"] += 1
code_info.branch_trails = branch_trails(code)
code_info.always_jumps = always_jumps(code)
# log(f"branch_trails for {code}:\n {code_info.branch_trails}")
added_arc = False
dest_info = code_info.branch_trails.get(instruction_offset)
# Re-map the destination offset through always-jumps to deal with NOP etc.
dests = {destination_offset}
while (dest := code_info.always_jumps.get(destination_offset)) is not None:
destination_offset = dest
dests.add(destination_offset)
# log(f"{dest_info = }")
if dest_info is not None:
for arc, offsets in dest_info.items():
if arc is None:
continue
if dests & offsets:
code_info.file_data.add(arc) # type: ignore
# log(f"adding {arc=}")
added_arc = True
break
if not added_arc:
# This could be an exception jumping from line to line.
assert code_info.byte_to_line is not None
l1 = code_info.byte_to_line[instruction_offset]
l2 = code_info.byte_to_line.get(destination_offset)
if l2 is not None and l1 != l2:
arc = (l1, l2)
code_info.file_data.add(arc) # type: ignore
# log(f"adding unforeseen {arc=}")
return DISABLE
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/templite.py 0000644 0001751 0001751 00000025072 15073731535 017050 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""A simple Python template renderer, for a nano-subset of Django syntax.
For a detailed discussion of this code, see this chapter from 500 Lines:
http://aosabook.org/en/500L/a-template-engine.html
"""
# Coincidentally named the same as http://code.activestate.com/recipes/496702/
from __future__ import annotations
import re
from typing import Any, Callable, NoReturn, cast
class TempliteSyntaxError(ValueError):
"""Raised when a template has a syntax error."""
pass
class TempliteValueError(ValueError):
"""Raised when an expression won't evaluate in a template."""
pass
class CodeBuilder:
"""Build source code conveniently."""
def __init__(self, indent: int = 0) -> None:
self.code: list[str | CodeBuilder] = []
self.indent_level = indent
def __str__(self) -> str:
return "".join(str(c) for c in self.code)
def add_line(self, line: str) -> None:
"""Add a line of source to the code.
Indentation and newline will be added for you, don't provide them.
"""
self.code.extend([" " * self.indent_level, line, "\n"])
def add_section(self) -> CodeBuilder:
"""Add a section, a sub-CodeBuilder."""
section = CodeBuilder(self.indent_level)
self.code.append(section)
return section
INDENT_STEP = 4 # PEP8 says so!
def indent(self) -> None:
"""Increase the current indent for following lines."""
self.indent_level += self.INDENT_STEP
def dedent(self) -> None:
"""Decrease the current indent for following lines."""
self.indent_level -= self.INDENT_STEP
def get_globals(self) -> dict[str, Any]:
"""Execute the code, and return a dict of globals it defines."""
# A check that the caller really finished all the blocks they started.
assert self.indent_level == 0
# Get the Python source as a single string.
python_source = str(self)
# Execute the source, defining globals, and return them.
global_namespace: dict[str, Any] = {}
exec(python_source, global_namespace)
return global_namespace
class Templite:
"""A simple template renderer, for a nano-subset of Django syntax.
Supported constructs are extended variable access::
{{var.modifier.modifier|filter|filter}}
loops::
{% for var in list %}...{% endfor %}
and ifs::
{% if var %}...{% endif %}
Comments are within curly-hash markers::
{# This will be ignored #}
Lines between `{% joined %}` and `{% endjoined %}` will have lines stripped
and joined. Be careful, this could join words together!
Any of these constructs can have a hyphen at the end (`-}}`, `-%}`, `-#}`),
which will collapse the white space following the tag.
Construct a Templite with the template text, then use `render` against a
dictionary context to create a finished string::
templite = Templite('''
Hello {{name|upper}}!
{% for topic in topics %}
You are interested in {{topic}}.
{% endif %}
''',
{"upper": str.upper},
)
text = templite.render({
"name": "Ned",
"topics": ["Python", "Geometry", "Juggling"],
})
"""
def __init__(self, text: str, *contexts: dict[str, Any]) -> None:
"""Construct a Templite with the given `text`.
`contexts` are dictionaries of values to use for future renderings.
These are good for filters and global values.
"""
self.context = {}
for context in contexts:
self.context.update(context)
self.all_vars: set[str] = set()
self.loop_vars: set[str] = set()
# We construct a function in source form, then compile it and hold onto
# it, and execute it to render the template.
code = CodeBuilder()
code.add_line("def render_function(context, do_dots):")
code.indent()
vars_code = code.add_section()
code.add_line("result = []")
code.add_line("append_result = result.append")
code.add_line("extend_result = result.extend")
code.add_line("to_str = str")
buffered: list[str] = []
def flush_output() -> None:
"""Force `buffered` to the code builder."""
if len(buffered) == 1:
code.add_line("append_result(%s)" % buffered[0])
elif len(buffered) > 1:
code.add_line("extend_result([%s])" % ", ".join(buffered))
del buffered[:]
ops_stack = []
# Split the text to form a list of tokens.
tokens = re.split(r"(?s)({{.*?}}|{%.*?%}|{#.*?#})", text)
squash = in_joined = False
for token in tokens:
if token.startswith("{"):
start, end = 2, -2
squash = (token[-3] == "-") # fmt: skip
if squash:
end = -3
if token.startswith("{#"):
# Comment: ignore it and move on.
continue
elif token.startswith("{{"):
# An expression to evaluate.
expr = self._expr_code(token[start:end].strip())
buffered.append("to_str(%s)" % expr)
else:
# token.startswith("{%")
# Action tag: split into words and parse further.
flush_output()
words = token[start:end].strip().split()
if words[0] == "if":
# An if statement: evaluate the expression to determine if.
if len(words) != 2:
self._syntax_error("Don't understand if", token)
ops_stack.append("if")
code.add_line("if %s:" % self._expr_code(words[1]))
code.indent()
elif words[0] == "for":
# A loop: iterate over expression result.
if len(words) != 4 or words[2] != "in":
self._syntax_error("Don't understand for", token)
ops_stack.append("for")
self._variable(words[1], self.loop_vars)
code.add_line(
f"for c_{words[1]} in {self._expr_code(words[3])}:",
)
code.indent()
elif words[0] == "joined":
ops_stack.append("joined")
in_joined = True
elif words[0].startswith("end"):
# Endsomething. Pop the ops stack.
if len(words) != 1:
self._syntax_error("Don't understand end", token)
end_what = words[0][3:]
if not ops_stack:
self._syntax_error("Too many ends", token)
start_what = ops_stack.pop()
if start_what != end_what:
self._syntax_error("Mismatched end tag", end_what)
if end_what == "joined":
in_joined = False
else:
code.dedent()
else:
self._syntax_error("Don't understand tag", words[0])
else:
# Literal content. If it isn't empty, output it.
if in_joined:
token = re.sub(r"\s*\n\s*", "", token.strip())
elif squash:
token = token.lstrip()
if token:
buffered.append(repr(token))
if ops_stack:
self._syntax_error("Unmatched action tag", ops_stack[-1])
flush_output()
for var_name in self.all_vars - self.loop_vars:
vars_code.add_line(f"c_{var_name} = context[{var_name!r}]")
code.add_line("return ''.join(result)")
code.dedent()
self._render_function = cast(
Callable[
[dict[str, Any], Callable[..., Any]],
str,
],
code.get_globals()["render_function"],
)
def _expr_code(self, expr: str) -> str:
"""Generate a Python expression for `expr`."""
if "|" in expr:
pipes = expr.split("|")
code = self._expr_code(pipes[0])
for func in pipes[1:]:
self._variable(func, self.all_vars)
code = f"c_{func}({code})"
elif "." in expr:
dots = expr.split(".")
code = self._expr_code(dots[0])
args = ", ".join(repr(d) for d in dots[1:])
code = f"do_dots({code}, {args})"
else:
self._variable(expr, self.all_vars)
code = "c_%s" % expr
return code
def _syntax_error(self, msg: str, thing: Any) -> NoReturn:
"""Raise a syntax error using `msg`, and showing `thing`."""
raise TempliteSyntaxError(f"{msg}: {thing!r}")
def _variable(self, name: str, vars_set: set[str]) -> None:
"""Track that `name` is used as a variable.
Adds the name to `vars_set`, a set of variable names.
Raises an syntax error if `name` is not a valid name.
"""
if not re.match(r"[_a-zA-Z][_a-zA-Z0-9]*$", name):
self._syntax_error("Not a valid name", name)
vars_set.add(name)
def render(self, context: dict[str, Any] | None = None) -> str:
"""Render this template by applying it to `context`.
`context` is a dictionary of values to use in this rendering.
"""
# Make the complete context we'll use.
render_context = dict(self.context)
if context:
render_context.update(context)
return self._render_function(render_context, self._do_dots)
def _do_dots(self, value: Any, *dots: str) -> Any:
"""Evaluate dotted expressions at run-time."""
for dot in dots:
try:
value = getattr(value, dot)
except AttributeError:
try:
value = value[dot]
except (TypeError, KeyError) as exc:
raise TempliteValueError(
f"Couldn't evaluate {value!r}.{dot}",
) from exc
if callable(value):
value = value()
return value
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/tomlconfig.py 0000644 0001751 0001751 00000016604 15073731535 017367 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""TOML configuration support for coverage.py"""
from __future__ import annotations
import os
import re
from collections.abc import Iterable
from typing import Any, Callable, TypeVar
from coverage import config, env
from coverage.exceptions import ConfigError
from coverage.misc import import_third_party, isolate_module, substitute_variables
from coverage.types import TConfigSectionOut, TConfigValueOut
os = isolate_module(os)
if env.PYVERSION >= (3, 11, 0, "alpha", 7):
import tomllib # pylint: disable=import-error
has_tomllib = True
else:
# TOML support on Python 3.10 and below is an install-time extra option.
tomllib, has_tomllib = import_third_party("tomli")
class TomlDecodeError(Exception):
"""An exception class that exists even when toml isn't installed."""
pass
TWant = TypeVar("TWant")
class TomlConfigParser:
"""TOML file reading with the interface of HandyConfigParser."""
# This class has the same interface as config.HandyConfigParser, no
# need for docstrings.
# pylint: disable=missing-function-docstring
def __init__(self, our_file: bool) -> None:
self.our_file = our_file
self.data: dict[str, Any] = {}
def read(self, filenames: Iterable[str]) -> list[str]:
# RawConfigParser takes a filename or list of filenames, but we only
# ever call this with a single filename.
assert isinstance(filenames, (bytes, str, os.PathLike))
filename = os.fspath(filenames)
try:
with open(filename, encoding="utf-8") as fp:
toml_text = fp.read()
except OSError:
return []
if has_tomllib:
try:
self.data = tomllib.loads(toml_text)
except tomllib.TOMLDecodeError as err:
raise TomlDecodeError(str(err)) from err
return [filename]
else:
has_toml = re.search(r"^\[tool\.coverage(\.|])", toml_text, flags=re.MULTILINE)
if self.our_file or has_toml:
# Looks like they meant to read TOML, but we can't read it.
msg = "Can't read {!r} without TOML support. Install with [toml] extra"
raise ConfigError(msg.format(filename))
return []
def _get_section(self, section: str) -> tuple[str | None, TConfigSectionOut | None]:
"""Get a section from the data.
Arguments:
section (str): A section name, which can be dotted.
Returns:
name (str): the actual name of the section that was found, if any,
or None.
data (str): the dict of data in the section, or None if not found.
"""
prefixes = ["tool.coverage."]
for prefix in prefixes:
real_section = prefix + section
parts = real_section.split(".")
try:
data = self.data[parts[0]]
for part in parts[1:]:
data = data[part]
except KeyError:
continue
break
else:
return None, None
return real_section, data
def _get(self, section: str, option: str) -> tuple[str, TConfigValueOut]:
"""Like .get, but returns the real section name and the value."""
name, data = self._get_section(section)
if data is None:
raise ConfigError(f"No section: {section!r}")
assert name is not None
try:
value = data[option]
except KeyError:
raise ConfigError(f"No option {option!r} in section: {name!r}") from None
return name, value
def _get_single(self, section: str, option: str) -> Any:
"""Get a single-valued option.
Performs environment substitution if the value is a string. Other types
will be converted later as needed.
"""
name, value = self._get(section, option)
if isinstance(value, str):
value = substitute_variables(value, os.environ)
return name, value
def has_option(self, section: str, option: str) -> bool:
_, data = self._get_section(section)
if data is None:
return False
return option in data
def real_section(self, section: str) -> str | None:
name, _ = self._get_section(section)
return name
def has_section(self, section: str) -> bool:
name, _ = self._get_section(section)
return bool(name)
def options(self, section: str) -> list[str]:
_, data = self._get_section(section)
if data is None:
raise ConfigError(f"No section: {section!r}")
return list(data.keys())
def get_section(self, section: str) -> TConfigSectionOut:
_, data = self._get_section(section)
return data or {}
def get(self, section: str, option: str) -> Any:
_, value = self._get_single(section, option)
return value
def _check_type(
self,
section: str,
option: str,
value: Any,
type_: type[TWant],
converter: Callable[[Any], TWant] | None,
type_desc: str,
) -> TWant:
"""Check that `value` has the type we want, converting if needed.
Returns the resulting value of the desired type.
"""
if isinstance(value, type_):
return value
if isinstance(value, str) and converter is not None:
try:
return converter(value)
except Exception as e:
raise ValueError(
f"Option [{section}]{option} couldn't convert to {type_desc}: {value!r}",
) from e
raise ValueError(
f"Option [{section}]{option} is not {type_desc}: {value!r}",
)
def getboolean(self, section: str, option: str) -> bool:
name, value = self._get_single(section, option)
bool_strings = {"true": True, "false": False}
return self._check_type(name, option, value, bool, bool_strings.__getitem__, "a boolean")
def getfile(self, section: str, option: str) -> str:
_, value = self._get_single(section, option)
return config.process_file_value(value)
def _get_list(self, section: str, option: str) -> tuple[str, list[str]]:
"""Get a list of strings, substituting environment variables in the elements."""
name, values = self._get(section, option)
values = self._check_type(name, option, values, list, None, "a list")
values = [substitute_variables(value, os.environ) for value in values]
return name, values
def getlist(self, section: str, option: str) -> list[str]:
_, values = self._get_list(section, option)
return values
def getregexlist(self, section: str, option: str) -> list[str]:
name, values = self._get_list(section, option)
return config.process_regexlist(name, option, values)
def getint(self, section: str, option: str) -> int:
name, value = self._get_single(section, option)
return self._check_type(name, option, value, int, int, "an integer")
def getfloat(self, section: str, option: str) -> float:
name, value = self._get_single(section, option)
if isinstance(value, int):
value = float(value)
return self._check_type(name, option, value, float, float, "a float")
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/tracer.pyi 0000644 0001751 0001751 00000002265 15073731535 016655 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Typing information for the constructs from our .c files."""
from typing import Any, Dict
from coverage.types import TFileDisposition, TTraceData, TTraceFn, Tracer
class CFileDisposition(TFileDisposition):
"""CFileDisposition is in ctracer/filedisp.c"""
canonical_filename: Any
file_tracer: Any
has_dynamic_filename: Any
original_filename: Any
reason: Any
source_filename: Any
trace: Any
def __init__(self) -> None: ...
class CTracer(Tracer):
"""CTracer is in ctracer/tracer.c"""
check_include: Any
concur_id_func: Any
data: TTraceData
disable_plugin: Any
file_tracers: Any
should_start_context: Any
should_trace: Any
should_trace_cache: Any
switch_context: Any
lock_data: Any
unlock_data: Any
trace_arcs: Any
warn: Any
def __init__(self) -> None: ...
def activity(self) -> bool: ...
def get_stats(self) -> Dict[str, int]: ...
def reset_activity(self) -> Any: ...
def start(self) -> TTraceFn: ...
def stop(self) -> None: ...
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/types.py 0000644 0001751 0001751 00000012736 15073731535 016374 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""
Types for use throughout coverage.py.
"""
from __future__ import annotations
import os
import pathlib
from collections.abc import Iterable, Mapping
from types import FrameType, ModuleType
from typing import TYPE_CHECKING, Any, Callable, Optional, Protocol
if TYPE_CHECKING:
from coverage.plugin import FileTracer
AnyCallable = Callable[..., Any]
## File paths
# For arguments that are file paths:
FilePath = str | os.PathLike[str]
# For testing FilePath arguments
FilePathClasses = [str, pathlib.Path]
FilePathType = type[str] | type[pathlib.Path]
## Python tracing
class TTraceFn(Protocol):
"""A Python trace function."""
def __call__(
self,
frame: FrameType,
event: str,
arg: Any,
lineno: TLineNo | None = None, # Our own twist, see collector.py
) -> TTraceFn | None: ...
## Coverage.py tracing
# Line numbers are pervasive enough that they deserve their own type.
TLineNo = int
# Bytecode offsets are pervasive enough that they deserve their own type.
TOffset = int
TArc = tuple[TLineNo, TLineNo]
class TFileDisposition(Protocol):
"""A simple value type for recording what to do with a file."""
original_filename: str
canonical_filename: str
source_filename: str | None
trace: bool
reason: str
file_tracer: FileTracer | None
has_dynamic_filename: bool
# When collecting data, we use a dictionary with a few possible shapes. The
# keys are always file names.
# - If measuring line coverage, the values are sets of line numbers.
# - If measuring arcs in the Python tracer, the values are sets of arcs (pairs
# of line numbers).
# - If measuring arcs in the C tracer, the values are sets of packed arcs (two
# line numbers combined into one integer).
TTraceFileData = set[TLineNo] | set[TArc] | set[int]
TTraceData = dict[str, TTraceFileData]
# Functions passed into collectors.
TShouldTraceFn = Callable[[str, FrameType], TFileDisposition]
TCheckIncludeFn = Callable[[str, FrameType], bool]
TShouldStartContextFn = Callable[[FrameType], str | None]
class Tracer(Protocol):
"""Anything that can report on Python execution."""
data: TTraceData
trace_arcs: bool
should_trace: TShouldTraceFn
should_trace_cache: Mapping[str, TFileDisposition | None]
should_start_context: TShouldStartContextFn | None
switch_context: Callable[[str | None], None] | None
lock_data: Callable[[], None]
unlock_data: Callable[[], None]
warn: TWarnFn
def __init__(self) -> None: ...
def start(self) -> TTraceFn | None:
"""Start this tracer, return a trace function if based on sys.settrace."""
def stop(self) -> None:
"""Stop this tracer."""
def activity(self) -> bool:
"""Has there been any activity?"""
def reset_activity(self) -> None:
"""Reset the activity() flag."""
def get_stats(self) -> dict[str, int] | None:
"""Return a dictionary of statistics, or None."""
## Coverage
# Many places use kwargs as Coverage kwargs.
TCovKwargs = Any
## Configuration
# One value read from a config file.
TConfigValueIn = Optional[bool | int | float | str | Iterable[str] | Mapping[str, Iterable[str]]]
TConfigValueOut = Optional[bool | int | float | str | list[str] | dict[str, list[str]]]
# An entire config section, mapping option names to values.
TConfigSectionIn = Mapping[str, TConfigValueIn]
TConfigSectionOut = Mapping[str, TConfigValueOut]
class TConfigurable(Protocol):
"""Something that can proxy to the coverage configuration settings."""
def get_option(self, option_name: str) -> TConfigValueOut | None:
"""Get an option from the configuration.
`option_name` is a colon-separated string indicating the section and
option name. For example, the ``branch`` option in the ``[run]``
section of the config file would be indicated with `"run:branch"`.
Returns the value of the option.
"""
def set_option(self, option_name: str, value: TConfigValueIn | TConfigSectionIn) -> None:
"""Set an option in the configuration.
`option_name` is a colon-separated string indicating the section and
option name. For example, the ``branch`` option in the ``[run]``
section of the config file would be indicated with `"run:branch"`.
`value` is the new value for the option.
"""
class TPluginConfig(Protocol):
"""Something that can provide options to a plugin."""
def get_plugin_options(self, plugin: str) -> TConfigSectionOut:
"""Get the options for a plugin."""
## Parsing
TMorf = ModuleType | str
TSourceTokenLines = Iterable[list[tuple[str, str]]]
## Plugins
class TPlugin(Protocol):
"""What all plugins have in common."""
_coverage_plugin_name: str
_coverage_enabled: bool
## Debugging
class TWarnFn(Protocol):
"""A callable warn() function."""
def __call__(self, msg: str, slug: str | None = None, once: bool = False) -> None: ...
class TDebugCtl(Protocol):
"""A DebugControl object, or something like it."""
def should(self, option: str) -> bool:
"""Decide whether to output debug information in category `option`."""
def write(self, msg: str) -> None:
"""Write a line of debug output."""
class TWritable(Protocol):
"""Anything that can be written to."""
def write(self, msg: str) -> None:
"""Write a message."""
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/version.py 0000644 0001751 0001751 00000002104 15073731535 016701 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""The version and URL for coverage.py"""
# This file is exec'ed in setup.py, don't import anything!
from __future__ import annotations
# version_info: same semantics as sys.version_info.
# _dev: the .devN suffix if any.
version_info = (7, 11, 0, "final", 0)
_dev = 0
def _make_version(
major: int,
minor: int,
micro: int,
releaselevel: str = "final",
serial: int = 0,
dev: int = 0,
) -> str:
"""Create a readable version string from version_info tuple components."""
assert releaselevel in ["alpha", "beta", "candidate", "final"]
version = f"{major}.{minor}.{micro}"
if releaselevel != "final":
short = {"alpha": "a", "beta": "b", "candidate": "rc"}[releaselevel]
version += f"{short}{serial}"
if dev != 0:
version += f".dev{dev}"
return version
__version__ = _make_version(*version_info, _dev)
__url__ = f"https://coverage.readthedocs.io/en/{__version__}"
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/coverage/xmlreport.py 0000644 0001751 0001751 00000023215 15073731535 017256 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""XML reporting for coverage.py"""
from __future__ import annotations
import os
import os.path
import sys
import time
import xml.dom.minidom
from collections.abc import Iterable
from dataclasses import dataclass
from typing import IO, TYPE_CHECKING, Any
from coverage import __version__, files
from coverage.misc import human_sorted, human_sorted_items, isolate_module
from coverage.plugin import FileReporter
from coverage.report_core import get_analysis_to_report
from coverage.results import Analysis
from coverage.types import TMorf
from coverage.version import __url__
if TYPE_CHECKING:
from coverage import Coverage
os = isolate_module(os)
DTD_URL = "https://raw.githubusercontent.com/cobertura/web/master/htdocs/xml/coverage-04.dtd"
def rate(hit: int, num: int) -> str:
"""Return the fraction of `hit`/`num`, as a string."""
if num == 0:
return "1"
else:
return f"{hit / num:.4g}"
@dataclass
class PackageData:
"""Data we keep about each "package" (in Java terms)."""
elements: dict[str, xml.dom.minidom.Element]
hits: int
lines: int
br_hits: int
branches: int
def appendChild(parent: Any, child: Any) -> None:
"""Append a child to a parent, in a way mypy will shut up about."""
parent.appendChild(child)
class XmlReporter:
"""A reporter for writing Cobertura-style XML coverage results."""
report_type = "XML report"
def __init__(self, coverage: Coverage) -> None:
self.coverage = coverage
self.config = self.coverage.config
self.source_paths = set()
if self.config.source:
for src in self.config.source:
if os.path.exists(src):
if self.config.relative_files:
src = src.rstrip(r"\/")
else:
src = files.canonical_filename(src)
self.source_paths.add(src)
self.packages: dict[str, PackageData] = {}
self.xml_out: xml.dom.minidom.Document
def report(self, morfs: Iterable[TMorf] | None, outfile: IO[str] | None = None) -> float:
"""Generate a Cobertura-compatible XML report for `morfs`.
`morfs` is a list of modules or file names.
`outfile` is a file object to write the XML to.
"""
# Initial setup.
outfile = outfile or sys.stdout
has_arcs = self.coverage.get_data().has_arcs()
# Create the DOM that will store the data.
impl = xml.dom.minidom.getDOMImplementation()
assert impl is not None
self.xml_out = impl.createDocument(None, "coverage", None)
# Write header stuff.
xcoverage = self.xml_out.documentElement
assert xcoverage is not None
xcoverage.setAttribute("version", __version__)
xcoverage.setAttribute("timestamp", str(int(time.time() * 1000)))
xcoverage.appendChild(
self.xml_out.createComment(
f" Generated by coverage.py: {__url__} ",
)
)
xcoverage.appendChild(self.xml_out.createComment(f" Based on {DTD_URL} "))
# Call xml_file for each file in the data.
for fr, analysis in get_analysis_to_report(self.coverage, morfs):
self.xml_file(fr, analysis, has_arcs)
xsources = self.xml_out.createElement("sources")
xcoverage.appendChild(xsources)
# Populate the XML DOM with the source info.
for path in human_sorted(self.source_paths):
xsource = self.xml_out.createElement("source")
appendChild(xsources, xsource)
txt = self.xml_out.createTextNode(path)
appendChild(xsource, txt)
lnum_tot, lhits_tot = 0, 0
bnum_tot, bhits_tot = 0, 0
xpackages = self.xml_out.createElement("packages")
xcoverage.appendChild(xpackages)
# Populate the XML DOM with the package info.
for pkg_name, pkg_data in human_sorted_items(self.packages.items()):
xpackage = self.xml_out.createElement("package")
appendChild(xpackages, xpackage)
xclasses = self.xml_out.createElement("classes")
appendChild(xpackage, xclasses)
for _, class_elt in human_sorted_items(pkg_data.elements.items()):
appendChild(xclasses, class_elt)
xpackage.setAttribute("name", pkg_name.replace(os.sep, "."))
xpackage.setAttribute("line-rate", rate(pkg_data.hits, pkg_data.lines))
if has_arcs:
branch_rate = rate(pkg_data.br_hits, pkg_data.branches)
else:
branch_rate = "0"
xpackage.setAttribute("branch-rate", branch_rate)
xpackage.setAttribute("complexity", "0")
lhits_tot += pkg_data.hits
lnum_tot += pkg_data.lines
bhits_tot += pkg_data.br_hits
bnum_tot += pkg_data.branches
xcoverage.setAttribute("lines-valid", str(lnum_tot))
xcoverage.setAttribute("lines-covered", str(lhits_tot))
xcoverage.setAttribute("line-rate", rate(lhits_tot, lnum_tot))
if has_arcs:
xcoverage.setAttribute("branches-valid", str(bnum_tot))
xcoverage.setAttribute("branches-covered", str(bhits_tot))
xcoverage.setAttribute("branch-rate", rate(bhits_tot, bnum_tot))
else:
xcoverage.setAttribute("branches-covered", "0")
xcoverage.setAttribute("branches-valid", "0")
xcoverage.setAttribute("branch-rate", "0")
xcoverage.setAttribute("complexity", "0")
# Write the output file.
outfile.write(serialize_xml(self.xml_out))
# Return the total percentage.
denom = lnum_tot + bnum_tot
if denom == 0:
pct = 0.0
else:
pct = 100.0 * (lhits_tot + bhits_tot) / denom
return pct
def xml_file(self, fr: FileReporter, analysis: Analysis, has_arcs: bool) -> None:
"""Add to the XML report for a single file."""
if self.config.skip_empty:
if analysis.numbers.n_statements == 0:
return
# Create the "lines" and "package" XML elements, which
# are populated later. Note that a package == a directory.
filename = fr.filename.replace("\\", "/")
for source_path in self.source_paths:
if not self.config.relative_files:
source_path = files.canonical_filename(source_path)
if filename.startswith(source_path.replace("\\", "/") + "/"):
rel_name = filename[len(source_path) + 1 :]
break
else:
rel_name = fr.relative_filename().replace("\\", "/")
self.source_paths.add(fr.filename[: -len(rel_name)].rstrip(r"\/"))
dirname = os.path.dirname(rel_name) or "."
dirname = "/".join(dirname.split("/")[: self.config.xml_package_depth])
package_name = dirname.replace("/", ".")
package = self.packages.setdefault(package_name, PackageData({}, 0, 0, 0, 0))
xclass: xml.dom.minidom.Element = self.xml_out.createElement("class")
appendChild(xclass, self.xml_out.createElement("methods"))
xlines = self.xml_out.createElement("lines")
appendChild(xclass, xlines)
xclass.setAttribute("name", os.path.relpath(rel_name, dirname))
xclass.setAttribute("filename", rel_name.replace("\\", "/"))
xclass.setAttribute("complexity", "0")
branch_stats = analysis.branch_stats()
missing_branch_arcs = analysis.missing_branch_arcs()
# For each statement, create an XML "line" element.
for line in sorted(analysis.statements):
xline = self.xml_out.createElement("line")
xline.setAttribute("number", str(line))
# Q: can we get info about the number of times a statement is
# executed? If so, that should be recorded here.
xline.setAttribute("hits", str(int(line not in analysis.missing)))
if has_arcs:
if line in branch_stats:
total, taken = branch_stats[line]
xline.setAttribute("branch", "true")
xline.setAttribute(
"condition-coverage",
f"{100 * taken // total}% ({taken}/{total})",
)
if line in missing_branch_arcs:
annlines = ["exit" if b < 0 else str(b) for b in missing_branch_arcs[line]]
xline.setAttribute("missing-branches", ",".join(annlines))
appendChild(xlines, xline)
class_lines = len(analysis.statements)
class_hits = class_lines - len(analysis.missing)
if has_arcs:
class_branches = sum(t for t, k in branch_stats.values())
missing_branches = sum(t - k for t, k in branch_stats.values())
class_br_hits = class_branches - missing_branches
else:
class_branches = 0
class_br_hits = 0
# Finalize the statistics that are collected in the XML DOM.
xclass.setAttribute("line-rate", rate(class_hits, class_lines))
if has_arcs:
branch_rate = rate(class_br_hits, class_branches)
else:
branch_rate = "0"
xclass.setAttribute("branch-rate", branch_rate)
package.elements[rel_name] = xclass
package.hits += class_hits
package.lines += class_lines
package.br_hits += class_br_hits
package.branches += class_branches
def serialize_xml(dom: xml.dom.minidom.Document) -> str:
"""Serialize a minidom node to XML."""
return dom.toprettyxml()
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9871895
coverage-7.11.0/coverage.egg-info/ 0000755 0001751 0001751 00000000000 15073731560 016335 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539503.0
coverage-7.11.0/coverage.egg-info/PKG-INFO 0000644 0001751 0001751 00000021376 15073731557 017451 0 ustar 00runner runner Metadata-Version: 2.4
Name: coverage
Version: 7.11.0
Summary: Code coverage measurement for Python
Home-page: https://github.com/nedbat/coveragepy
Author: Ned Batchelder and 243 others
Author-email: ned@nedbatchelder.com
License: Apache-2.0
Project-URL: Documentation, https://coverage.readthedocs.io/en/7.11.0
Project-URL: Funding, https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=pypi
Project-URL: Issues, https://github.com/nedbat/coveragepy/issues
Project-URL: Mastodon, https://hachyderm.io/@coveragepy
Project-URL: Mastodon (nedbat), https://hachyderm.io/@nedbat
Keywords: code coverage testing
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Provides-Extra: toml
Requires-Dist: tomli; python_full_version <= "3.11.0a6" and extra == "toml"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary
.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
===========
Coverage.py
===========
Code coverage measurement for Python.
.. image:: https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg
:target: https://vshymanskyy.github.io/StandWithUkraine
:alt: Stand with Ukraine
-------------
| |kit| |license| |versions|
| |test-status| |quality-status| |docs| |metacov|
| |tidelift| |sponsor| |stars| |mastodon-coveragepy| |mastodon-nedbat|
|bluesky-nedbat|
Coverage.py measures code coverage, typically during test execution. It uses
the code analysis tools and tracing hooks provided in the Python standard
library to determine which lines are executable, and which have been executed.
Coverage.py runs on these versions of Python:
.. PYVERSIONS
* Python 3.10 through 3.15 alpha, including free-threading.
* PyPy3 versions 3.10 and 3.11.
Documentation is on `Read the Docs`_. Code repository and issue tracker are on
`GitHub`_.
.. _Read the Docs: https://coverage.readthedocs.io/en/7.11.0/
.. _GitHub: https://github.com/nedbat/coveragepy
**New in 7.x:**
``[run] patch`` setting;
``--save-signal`` option;
``[run] core`` setting;
``[run] source_dirs`` setting;
``Coverage.branch_stats()``;
multi-line exclusion patterns;
function/class reporting;
experimental support for sys.monitoring;
dropped support for Python up to 3.9;
added ``Coverage.collect()`` context manager;
improved data combining;
``[run] exclude_also`` setting;
``report --format=``;
type annotations.
**New in 6.x:**
dropped support for Python 2.7, 3.5, and 3.6;
write data on SIGTERM;
added support for 3.10 match/case statements.
For Enterprise
--------------
.. |tideliftlogo| image:: https://nedbatchelder.com/pix/Tidelift_Logo_small.png
:alt: Tidelift
:target: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=readme
.. list-table::
:widths: 10 100
* - |tideliftlogo|
- `Available as part of the Tidelift Subscription. `_
Coverage and thousands of other packages are working with
Tidelift to deliver one enterprise subscription that covers all of the open
source you use. If you want the flexibility of open source and the confidence
of commercial-grade software, this is for you.
`Learn more. `_
Getting Started
---------------
Looking to run ``coverage`` on your test suite? See the `Quick Start section`_
of the docs.
.. _Quick Start section: https://coverage.readthedocs.io/en/7.11.0/#quick-start
Change history
--------------
The complete history of changes is on the `change history page`_.
.. _change history page: https://coverage.readthedocs.io/en/7.11.0/changes.html
Code of Conduct
---------------
Everyone participating in the coverage.py project is expected to treat other
people with respect and to follow the guidelines articulated in the `Python
Community Code of Conduct`_.
.. _Python Community Code of Conduct: https://www.python.org/psf/codeofconduct/
Contributing
------------
Found a bug? Want to help improve the code or documentation? See the
`Contributing section`_ of the docs.
.. _Contributing section: https://coverage.readthedocs.io/en/7.11.0/contributing.html
Security
--------
To report a security vulnerability, please use the `Tidelift security
contact`_. Tidelift will coordinate the fix and disclosure.
.. _Tidelift security contact: https://tidelift.com/security
License
-------
Licensed under the `Apache 2.0 License`_. For details, see `NOTICE.txt`_.
.. _Apache 2.0 License: http://www.apache.org/licenses/LICENSE-2.0
.. _NOTICE.txt: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. |test-status| image:: https://github.com/nedbat/coveragepy/actions/workflows/testsuite.yml/badge.svg?branch=master&event=push
:target: https://github.com/nedbat/coveragepy/actions/workflows/testsuite.yml
:alt: Test suite status
.. |quality-status| image:: https://github.com/nedbat/coveragepy/actions/workflows/quality.yml/badge.svg?branch=master&event=push
:target: https://github.com/nedbat/coveragepy/actions/workflows/quality.yml
:alt: Quality check status
.. |docs| image:: https://readthedocs.org/projects/coverage/badge/?version=latest&style=flat
:target: https://coverage.readthedocs.io/en/7.11.0/
:alt: Documentation
.. |kit| image:: https://img.shields.io/pypi/v/coverage
:target: https://pypi.org/project/coverage/
:alt: PyPI status
.. |versions| image:: https://img.shields.io/pypi/pyversions/coverage.svg?logo=python&logoColor=FBE072
:target: https://pypi.org/project/coverage/
:alt: Python versions supported
.. |license| image:: https://img.shields.io/pypi/l/coverage.svg
:target: https://github.com/nedbat/coveragepy/blob/master/LICENSE.txt
:alt: License
.. |metacov| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/nedbat/8c6980f77988a327348f9b02bbaf67f5/raw/metacov.json
:target: https://nedbat.github.io/coverage-reports/latest.html
:alt: Coverage reports
.. |tidelift| image:: https://tidelift.com/badges/package/pypi/coverage
:target: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=readme
:alt: Tidelift
.. |stars| image:: https://img.shields.io/github/stars/nedbat/coveragepy.svg?logo=github&style=flat
:target: https://github.com/nedbat/coveragepy/stargazers
:alt: GitHub stars
.. |mastodon-nedbat| image:: https://img.shields.io/badge/dynamic/json?style=flat&labelColor=450657&logo=mastodon&logoColor=ffffff&label=@nedbat&query=followers_count&url=https%3A%2F%2Fhachyderm.io%2Fapi%2Fv1%2Faccounts%2Flookup%3Facct=nedbat
:target: https://hachyderm.io/@nedbat
:alt: nedbat on Mastodon
.. |mastodon-coveragepy| image:: https://img.shields.io/badge/dynamic/json?style=flat&labelColor=450657&logo=mastodon&logoColor=ffffff&label=@coveragepy&query=followers_count&url=https%3A%2F%2Fhachyderm.io%2Fapi%2Fv1%2Faccounts%2Flookup%3Facct=coveragepy
:target: https://hachyderm.io/@coveragepy
:alt: coveragepy on Mastodon
.. |bluesky-nedbat| image:: https://img.shields.io/badge/dynamic/json?style=flat&color=96a3b0&labelColor=3686f7&logo=icloud&logoColor=white&label=@nedbat&url=https%3A%2F%2Fpublic.api.bsky.app%2Fxrpc%2Fapp.bsky.actor.getProfile%3Factor=nedbat.com&query=followersCount
:target: https://bsky.app/profile/nedbat.com
:alt: nedbat on Bluesky
.. |sponsor| image:: https://img.shields.io/badge/%E2%9D%A4-Sponsor%20me-brightgreen?style=flat&logo=GitHub
:target: https://github.com/sponsors/nedbat
:alt: Sponsor me on GitHub
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539503.0
coverage-7.11.0/coverage.egg-info/SOURCES.txt 0000644 0001751 0001751 00000025245 15073731557 020237 0 ustar 00runner runner .editorconfig
.git-blame-ignore-revs
.ignore
.pre-commit-config.yaml
.readthedocs.yaml
CHANGES.rst
CITATION.cff
CONTRIBUTORS.txt
LICENSE.txt
MANIFEST.in
Makefile
NOTICE.txt
README.rst
__main__.py
howto.txt
igor.py
metacov.ini
pyproject.toml
setup.py
tox.ini
.github/CODE_OF_CONDUCT.md
.github/FUNDING.yml
.github/SECURITY.md
.github/dependabot.yml
.github/zizmor.yml
.github/ISSUE_TEMPLATE/bug_report.md
.github/ISSUE_TEMPLATE/config.yml
.github/ISSUE_TEMPLATE/feature_request.md
.github/ISSUE_TEMPLATE/support.md
.github/workflows/codeql-analysis.yml
.github/workflows/coverage.yml
.github/workflows/dependency-review.yml
.github/workflows/kit.yml
.github/workflows/publish.yml
.github/workflows/python-nightly.yml
.github/workflows/quality.yml
.github/workflows/testsuite.yml
ci/README.txt
ci/comment_on_fixes.py
ci/session.py
ci/trigger_action.py
ci/update_rtfd.py
coverage/__init__.py
coverage/__main__.py
coverage/annotate.py
coverage/bytecode.py
coverage/cmdline.py
coverage/collector.py
coverage/config.py
coverage/context.py
coverage/control.py
coverage/core.py
coverage/data.py
coverage/debug.py
coverage/disposition.py
coverage/env.py
coverage/exceptions.py
coverage/execfile.py
coverage/files.py
coverage/html.py
coverage/inorout.py
coverage/jsonreport.py
coverage/lcovreport.py
coverage/misc.py
coverage/multiproc.py
coverage/numbits.py
coverage/parser.py
coverage/patch.py
coverage/phystokens.py
coverage/plugin.py
coverage/plugin_support.py
coverage/py.typed
coverage/python.py
coverage/pytracer.py
coverage/regions.py
coverage/report.py
coverage/report_core.py
coverage/results.py
coverage/sqldata.py
coverage/sqlitedb.py
coverage/sysmon.py
coverage/templite.py
coverage/tomlconfig.py
coverage/tracer.pyi
coverage/types.py
coverage/version.py
coverage/xmlreport.py
coverage.egg-info/PKG-INFO
coverage.egg-info/SOURCES.txt
coverage.egg-info/dependency_links.txt
coverage.egg-info/entry_points.txt
coverage.egg-info/not-zip-safe
coverage.egg-info/requires.txt
coverage.egg-info/top_level.txt
coverage/ctracer/datastack.c
coverage/ctracer/datastack.h
coverage/ctracer/filedisp.c
coverage/ctracer/filedisp.h
coverage/ctracer/module.c
coverage/ctracer/stats.h
coverage/ctracer/tracer.c
coverage/ctracer/tracer.h
coverage/ctracer/util.h
coverage/htmlfiles/coverage_html.js
coverage/htmlfiles/favicon_32.png
coverage/htmlfiles/index.html
coverage/htmlfiles/keybd_closed.png
coverage/htmlfiles/pyfile.html
coverage/htmlfiles/style.css
coverage/htmlfiles/style.scss
doc/api.rst
doc/api_coverage.rst
doc/api_coveragedata.rst
doc/api_exceptions.rst
doc/api_module.rst
doc/api_plugin.rst
doc/branch.rst
doc/changes.rst
doc/cog_helpers.py
doc/conf.py
doc/config.rst
doc/contexts.rst
doc/contributing.rst
doc/dbschema.rst
doc/dict.txt
doc/excluding.rst
doc/faq.rst
doc/howitworks.rst
doc/index.rst
doc/install.rst
doc/messages.rst
doc/migrating.rst
doc/other.rst
doc/plugins.rst
doc/python-coverage.1.txt
doc/requirements.in
doc/requirements.pip
doc/sleepy.rst
doc/source.rst
doc/subprocess.rst
doc/trouble.rst
doc/whatsnew5x.rst
doc/_static/coverage.css
doc/commands/cmd_annotate.rst
doc/commands/cmd_combine.rst
doc/commands/cmd_debug.rst
doc/commands/cmd_erase.rst
doc/commands/cmd_html.rst
doc/commands/cmd_json.rst
doc/commands/cmd_lcov.rst
doc/commands/cmd_report.rst
doc/commands/cmd_reporting.rst
doc/commands/cmd_run.rst
doc/commands/cmd_xml.rst
doc/commands/index.rst
doc/media/Tidelift_Logos_RGB_Tidelift_Shorthand_On-White.png
doc/media/Tidelift_Logos_RGB_Tidelift_Shorthand_On-White_small.png
doc/media/sleepy-snake-600.png
doc/media/sleepy-snake-circle-150.png
doc/sample_html/favicon_32_cb_58284776.png
doc/sample_html/keybd_closed_cb_ce680311.png
lab/README.txt
lab/branches.py
lab/compare_times.sh
lab/coverage-04.dtd
lab/extract_code.py
lab/goals.py
lab/hack_pyc.py
lab/parse_all.py
lab/parser.py
lab/pick.py
lab/platform_info.py
lab/run_sysmon.py
lab/run_trace.py
lab/select_contexts.py
lab/show_platform.py
lab/show_pyc.py
lab/treetopy.sh
lab/warn_executed.py
lab/warn_executed.toml
lab/notes/arcs-to-branches.txt
lab/notes/bug1303.txt
lab/notes/pypy-738-decorated-functions.txt
requirements/dev.in
requirements/dev.pip
requirements/kit.in
requirements/kit.pip
requirements/light-threads.in
requirements/light-threads.pip
requirements/mypy.in
requirements/mypy.pip
requirements/pins.pip
requirements/pip.in
requirements/pip.pip
requirements/pytest.in
requirements/pytest.pip
requirements/tox.in
requirements/tox.pip
tests/__init__.py
tests/conftest.py
tests/coveragetest.py
tests/covmodzip1.py
tests/goldtest.py
tests/helpers.py
tests/mixins.py
tests/osinfo.py
tests/plugin1.py
tests/plugin2.py
tests/plugin_config.py
tests/select_plugin.py
tests/stress_phystoken.tok
tests/stress_phystoken_dos.tok
tests/test_annotate.py
tests/test_api.py
tests/test_arcs.py
tests/test_bytecode.py
tests/test_cmdline.py
tests/test_collector.py
tests/test_concurrency.py
tests/test_config.py
tests/test_context.py
tests/test_core.py
tests/test_coverage.py
tests/test_data.py
tests/test_debug.py
tests/test_execfile.py
tests/test_filereporter.py
tests/test_files.py
tests/test_goldtest.py
tests/test_html.py
tests/test_json.py
tests/test_lcov.py
tests/test_misc.py
tests/test_mixins.py
tests/test_numbits.py
tests/test_oddball.py
tests/test_parser.py
tests/test_phystokens.py
tests/test_plugins.py
tests/test_process.py
tests/test_python.py
tests/test_regions.py
tests/test_report.py
tests/test_report_common.py
tests/test_report_core.py
tests/test_results.py
tests/test_setup.py
tests/test_sqlitedb.py
tests/test_templite.py
tests/test_testing.py
tests/test_venv.py
tests/test_version.py
tests/test_xml.py
tests/testenv.py
tests/gold/README.rst
tests/gold/annotate/anno_dir/multi.py,cover
tests/gold/annotate/anno_dir/z_80084bf2fba02475___init__.py,cover
tests/gold/annotate/anno_dir/z_80084bf2fba02475_a.py,cover
tests/gold/annotate/anno_dir/z_b039179a8a4ce2c2___init__.py,cover
tests/gold/annotate/anno_dir/z_b039179a8a4ce2c2_b.py,cover
tests/gold/annotate/encodings/utf8.py,cover
tests/gold/annotate/mae/mae.py,cover
tests/gold/annotate/multi/multi.py,cover
tests/gold/annotate/multi/a/__init__.py,cover
tests/gold/annotate/multi/a/a.py,cover
tests/gold/annotate/multi/b/__init__.py,cover
tests/gold/annotate/multi/b/b.py,cover
tests/gold/annotate/white/white.py,cover
tests/gold/html/Makefile
tests/gold/html/a/a_py.html
tests/gold/html/a/class_index.html
tests/gold/html/a/function_index.html
tests/gold/html/a/index.html
tests/gold/html/b_branch/b_py.html
tests/gold/html/b_branch/class_index.html
tests/gold/html/b_branch/function_index.html
tests/gold/html/b_branch/index.html
tests/gold/html/bom/bom_py.html
tests/gold/html/bom/class_index.html
tests/gold/html/bom/function_index.html
tests/gold/html/bom/index.html
tests/gold/html/contexts/class_index.html
tests/gold/html/contexts/function_index.html
tests/gold/html/contexts/index.html
tests/gold/html/contexts/two_tests_py.html
tests/gold/html/isolatin1/class_index.html
tests/gold/html/isolatin1/function_index.html
tests/gold/html/isolatin1/index.html
tests/gold/html/isolatin1/isolatin1_py.html
tests/gold/html/multiline/class_index.html
tests/gold/html/multiline/function_index.html
tests/gold/html/multiline/index.html
tests/gold/html/multiline/multiline_py.html
tests/gold/html/omit_1/class_index.html
tests/gold/html/omit_1/function_index.html
tests/gold/html/omit_1/index.html
tests/gold/html/omit_1/m1_py.html
tests/gold/html/omit_1/m2_py.html
tests/gold/html/omit_1/m3_py.html
tests/gold/html/omit_1/main_py.html
tests/gold/html/omit_2/class_index.html
tests/gold/html/omit_2/function_index.html
tests/gold/html/omit_2/index.html
tests/gold/html/omit_2/m2_py.html
tests/gold/html/omit_2/m3_py.html
tests/gold/html/omit_2/main_py.html
tests/gold/html/omit_3/class_index.html
tests/gold/html/omit_3/function_index.html
tests/gold/html/omit_3/index.html
tests/gold/html/omit_3/m3_py.html
tests/gold/html/omit_3/main_py.html
tests/gold/html/omit_4/class_index.html
tests/gold/html/omit_4/function_index.html
tests/gold/html/omit_4/index.html
tests/gold/html/omit_4/m1_py.html
tests/gold/html/omit_4/m3_py.html
tests/gold/html/omit_4/main_py.html
tests/gold/html/omit_5/class_index.html
tests/gold/html/omit_5/function_index.html
tests/gold/html/omit_5/index.html
tests/gold/html/omit_5/m1_py.html
tests/gold/html/omit_5/main_py.html
tests/gold/html/other/blah_blah_other_py.html
tests/gold/html/other/class_index.html
tests/gold/html/other/function_index.html
tests/gold/html/other/here_py.html
tests/gold/html/other/index.html
tests/gold/html/partial/class_index.html
tests/gold/html/partial/function_index.html
tests/gold/html/partial/index.html
tests/gold/html/partial/partial_py.html
tests/gold/html/styled/a_py.html
tests/gold/html/styled/class_index.html
tests/gold/html/styled/function_index.html
tests/gold/html/styled/index.html
tests/gold/html/styled/myextra.css
tests/gold/html/styled/style.css
tests/gold/html/support/coverage_html_cb_6fb7b396.js
tests/gold/html/support/favicon_32_cb_58284776.png
tests/gold/html/support/keybd_closed_cb_ce680311.png
tests/gold/html/support/style_cb_6b508a39.css
tests/gold/html/unicode/class_index.html
tests/gold/html/unicode/function_index.html
tests/gold/html/unicode/index.html
tests/gold/html/unicode/unicode_py.html
tests/gold/testing/getty/gettysburg.txt
tests/gold/testing/xml/output.xml
tests/gold/xml/x_xml/coverage.xml
tests/gold/xml/y_xml_branch/coverage.xml
tests/js/index.html
tests/js/tests.js
tests/modules/covmod1.py
tests/modules/runmod1.py
tests/modules/usepkgs.py
tests/modules/aa/__init__.py
tests/modules/aa/afile.odd.py
tests/modules/aa/afile.py
tests/modules/aa/zfile.py
tests/modules/aa/bb/__init__.py
tests/modules/aa/bb/bfile.odd.py
tests/modules/aa/bb/bfile.py
tests/modules/aa/bb.odd/bfile.py
tests/modules/aa/bb/cc/__init__.py
tests/modules/aa/bb/cc/cfile.py
tests/modules/ambiguous/__init__.py
tests/modules/ambiguous/pkg1/__init__.py
tests/modules/ambiguous/pkg1/ambiguous.py
tests/modules/namespace_420/sub1/__init__.py
tests/modules/pkg1/__init__.py
tests/modules/pkg1/__main__.py
tests/modules/pkg1/p1a.py
tests/modules/pkg1/p1b.py
tests/modules/pkg1/p1c.py
tests/modules/pkg1/runmod2.py
tests/modules/pkg1/sub/__init__.py
tests/modules/pkg1/sub/__main__.py
tests/modules/pkg1/sub/ps1a.py
tests/modules/pkg1/sub/runmod3.py
tests/modules/pkg2/__init__.py
tests/modules/pkg2/p2a.py
tests/modules/pkg2/p2b.py
tests/modules/plugins/__init__.py
tests/modules/plugins/a_plugin.py
tests/modules/plugins/another.py
tests/modules/process_test/__init__.py
tests/modules/process_test/try_execfile.py
tests/moremodules/namespace_420/sub2/__init__.py
tests/moremodules/othermods/__init__.py
tests/moremodules/othermods/othera.py
tests/moremodules/othermods/otherb.py
tests/moremodules/othermods/sub/__init__.py
tests/moremodules/othermods/sub/osa.py
tests/moremodules/othermods/sub/osb.py
tests/qunit/jquery.tmpl.min.js
tests/zipsrc/zip1/__init__.py
tests/zipsrc/zip1/zip1.py ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539503.0
coverage-7.11.0/coverage.egg-info/dependency_links.txt 0000644 0001751 0001751 00000000001 15073731557 022411 0 ustar 00runner runner
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539503.0
coverage-7.11.0/coverage.egg-info/entry_points.txt 0000644 0001751 0001751 00000000173 15073731557 021642 0 ustar 00runner runner [console_scripts]
coverage = coverage.cmdline:main
coverage-3.11 = coverage.cmdline:main
coverage3 = coverage.cmdline:main
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539503.0
coverage-7.11.0/coverage.egg-info/not-zip-safe 0000644 0001751 0001751 00000000001 15073731557 020571 0 ustar 00runner runner
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539503.0
coverage-7.11.0/coverage.egg-info/requires.txt 0000644 0001751 0001751 00000000070 15073731557 020740 0 ustar 00runner runner
[toml]
[toml:python_full_version <= "3.11.0a6"]
tomli
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539503.0
coverage-7.11.0/coverage.egg-info/top_level.txt 0000644 0001751 0001751 00000000011 15073731557 021065 0 ustar 00runner runner coverage
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9481895
coverage-7.11.0/doc/ 0000755 0001751 0001751 00000000000 15073731560 013615 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9481895
coverage-7.11.0/doc/_static/ 0000755 0001751 0001751 00000000000 15073731560 015243 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/_static/coverage.css 0000644 0001751 0001751 00000005116 15073731535 017555 0 ustar 00runner runner a:hover {
text-decoration: underline;
}
img.tideliftlogo {
border: 1px solid #888;
margin-top: .5em !important;
}
.rst-content ol.arabic li {
margin-bottom: 12px;
}
.rst-content h3, .rst-content h4, .rst-content h5, .rst-content h6 {
/* This makes config.rst look a little better, but the paras are still too
* spaced out.
*/
margin-bottom: 12px;
}
.ui.menu {
font-family: Helvetica;
min-height: 0;
}
.ui.tabular.menu .item {
padding: .25em 1em;
}
.ui.menu .item {
padding: 0;
}
.sig {
font-family: Consolas,"Andale Mono WT","Andale Mono","Lucida Console","Lucida Sans Typewriter","DejaVu Sans Mono","Bitstream Vera Sans Mono","Liberation Mono","Nimbus Mono L",Monaco,"Courier New",Courier,monospace;
}
.sig-name, .sig-prename {
font-size: 1.1em;
font-weight: bold;
color: black;
}
.rst-content dl dt.sig {
font-weight: inherit;
}
/* .. parsed-literal:: isn't styled like other
blocks!? */
.rst-content pre.literal-block {
white-space: pre;
padding: 12px 12px !important;
font-family: Consolas,"Andale Mono WT","Andale Mono","Lucida Console","Lucida Sans Typewriter","DejaVu Sans Mono","Bitstream Vera Sans Mono","Liberation Mono","Nimbus Mono L",Monaco,"Courier New",Courier,monospace;
font-size: 12px;
display: block;
overflow: auto;
color: #404040;
background: #efc;
}
/* I'm not sure why I had to make this so specific to get it to take effect... */
div.rst-content div.document div.wy-table-responsive table.docutils.align-default tbody tr td {
vertical-align: top !important;
}
/* And this doesn't work, and I guess I just have to live with it. */
div.rst-content div.document div.wy-table-responsive table.docutils.align-default tbody tr td .line-block {
margin-bottom: 0 !important;
}
/* sphinx-code-tabs */
/* Some selectors here are extra-specific (.container) because this file comes
* before code-tabs.css, so we need the specificity to override it.
*/
div.tabs.container > ul.tabbar > li.tabbutton {
color: #666;
background-color: #ddd;
border-color: #aaa;
}
div.tabs.container > ul.tabbar > li.tabbutton:hover {
background-color: #eee;
}
div.tabs.container > ul.tabbar > li.tabbutton.selected {
color: black;
background-color: #fff;
border-color: #aaa;
border-bottom-color: #fff;
}
div.tabs.container > ul.tabbar > li.tabbutton.selected:hover {
background-color: #fff;
}
div.tabs.container {
margin-bottom: 1em;
}
div.tab.selected {
border: 1px solid #ccc;
border-radius: 0 .5em .5em .5em;
}
div.tab.codetab.selected {
border: none;
}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/api.rst 0000644 0001751 0001751 00000003762 15073731535 015132 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _api:
===============
Coverage.py API
===============
There are a few different ways to use coverage.py programmatically.
The API to coverage.py is in a module called :mod:`coverage`. Most of the
interface is in the :class:`coverage.Coverage` class. Methods on the Coverage
object correspond roughly to operations available in the command line
interface. For example, a simple use would be::
import coverage
cov = coverage.Coverage()
cov.start()
# .. call your code ..
cov.stop()
cov.save()
cov.html_report()
Any of the methods can raise specialized exceptions described in
:ref:`api_exceptions`.
Coverage.py supports plugins that can change its behavior, to collect
information from non-Python files, or to perform complex configuration. See
:ref:`api_plugin` for details.
If you want to access the data that coverage.py has collected, the
:class:`coverage.CoverageData` class provides an API to read coverage.py data
files.
.. warning::
Only the published documented portions of the API are supported. Other
names you may find in modules or objects can change their behavior at any
time. Please limit yourself to documented methods to avoid problems.
All internal code in coverage.py has docstrings; this does not make them
part of the public supported API. Many internal names have no leading
underscore; this does not make them part of the public supported API. If
classes or functions are not documented in this published documentation,
they are not supported.
For more intensive data use, you might want to access the coverage.py database
file directly. The schema is subject to change, so this is for advanced uses
only. :ref:`dbschema` explains more.
.. toctree::
:maxdepth: 1
api_coverage
api_exceptions
api_module
api_plugin
api_coveragedata
dbschema
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/api_coverage.rst 0000644 0001751 0001751 00000000505 15073731535 016775 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _api_coverage:
The Coverage class
------------------
.. autoclass:: coverage.Coverage
:members:
:exclude-members: sys_info
:special-members: __init__
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/api_coveragedata.rst 0000644 0001751 0001751 00000000515 15073731535 017630 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _api_coveragedata:
The CoverageData class
----------------------
.. versionadded:: 4.0
.. autoclass:: coverage.CoverageData
:members:
:special-members: __init__
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/api_exceptions.rst 0000644 0001751 0001751 00000000452 15073731535 017364 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _api_exceptions:
Coverage exceptions
-------------------
.. automodule:: coverage.exceptions
:members:
:member-order: bysource
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/api_module.rst 0000644 0001751 0001751 00000002220 15073731535 016463 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _api_module:
coverage module
---------------
.. module:: coverage
The most important thing in the coverage module is the
:class:`coverage.Coverage` class, described in :ref:`api_coverage`, but there
are a few other things also.
.. data:: version_info
A tuple of five elements, similar to :data:`sys.version_info
`: *major*, *minor*, *micro*, *releaselevel*, and
*serial*. All values except *releaselevel* are integers; the release level is
``'alpha'``, ``'beta'``, ``'candidate'``, or ``'final'``. Unlike
:data:`sys.version_info `, the elements are not
available by name.
.. data:: __version__
A string with the version of coverage.py, for example, ``"5.0b2"``.
.. autoexception:: coverage.CoverageException
Starting coverage.py automatically
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This function is used to start coverage measurement automatically when Python
starts. See :ref:`subprocess` for details.
.. autofunction:: coverage.process_startup
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/api_plugin.rst 0000644 0001751 0001751 00000001366 15073731535 016506 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _api_plugin:
===============
Plug-in classes
===============
.. automodule:: coverage.plugin
The CoveragePlugin class
------------------------
.. autoclass:: coverage.CoveragePlugin
:members:
:member-order: bysource
The FileTracer class
--------------------
.. autoclass:: coverage.FileTracer
:members:
:member-order: bysource
The FileReporter class
----------------------
.. autoclass:: coverage.FileReporter
:members:
:member-order: bysource
The CodeRegion class
--------------------
.. autoclass:: coverage.CodeRegion
:members:
:member-order: bysource
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/branch.rst 0000644 0001751 0001751 00000010554 15073731535 015613 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _branch:
===========================
Branch coverage measurement
===========================
.. highlight:: python
:linenothreshold: 5
In addition to the usual statement coverage, coverage.py also supports branch
coverage measurement. Where a line in your program could jump to more than one
next line, coverage.py tracks which of those destinations are actually visited,
and flags lines that haven't visited all of their possible destinations.
For example::
def my_partial_fn(x):
if x:
y = 10
return y
my_partial_fn(1)
In this code, line 2 is an ``if`` statement which can go next to either line 3
or line 4. Statement coverage would show all lines of the function as executed.
But the if was never evaluated as false, so line 2 never jumps to line 4.
Branch coverage will flag this code as not fully covered because of the missing
jump from line 2 to line 4. This is known as a partial branch.
How to measure branch coverage
------------------------------
To measure branch coverage, run coverage.py with the ``--branch`` flag::
coverage run --branch myprog.py
When you report on the results with ``coverage report`` or ``coverage html``,
the percentage of branch possibilities taken will be included in the percentage
covered total for each file. The coverage percentage for a file is the actual
executions divided by the execution opportunities. Each line in the file is an
execution opportunity, as is each branch destination.
The HTML report gives information about which lines had missing branches. Lines
that were missing some branches are shown in yellow, with an annotation at the
far right showing branch destination line numbers that were not exercised.
The XML and JSON reports produced by ``coverage xml`` and ``coverage json``
also include branch information, including separate statement and branch
coverage percentages.
How it works
------------
When measuring branches, coverage.py collects pairs of line numbers, a source
and destination for each transition from one line to another. Static analysis
of the source provides a list of possible transitions. Comparing the measured
to the possible indicates missing branches.
The idea of tracking how lines follow each other was from `Titus Brown`__.
Thanks, Titus!
__ http://ivory.idyll.org/blog
Excluding code
--------------
If you have :ref:`excluded code `, a conditional will not be counted
as a branch if one of its choices is excluded::
def only_one_choice(x):
if x:
blah1()
blah2()
else: # pragma: no cover
# x is always true.
blah3()
Because the ``else`` clause is excluded, the ``if`` only has one possible next
line, so it isn't considered a branch at all.
Structurally partial branches
-----------------------------
Sometimes branching constructs are used in unusual ways that don't actually
branch. For example::
while True:
if cond:
break
do_something()
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. In these cases, the line
will not be marked as a partial branch.
But there are many ways in your own code to write intentionally partial
branches, and you don't want coverage.py pestering you about them. You can
tell coverage.py that you don't want them flagged by marking them with a
pragma::
i = 0
while i < 999999999: # pragma: no branch
if eventually():
break
Here the while loop will never complete because the break will always be taken
at some point. Coverage.py can't work that out on its own, but the "no branch"
pragma indicates that the branch is known to be partial, and the line is not
flagged.
Generator expressions
=====================
Generator expressions may also report partial branch coverage. Consider the
following example::
value = next(i in range(1))
While we might expect this line of code to be reported as covered, the
generator did not iterate until ``StopIteration`` is raised, the indication
that the loop is complete. This is another case
where adding ``# pragma: no branch`` may be desirable.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/changes.rst 0000644 0001751 0001751 00000333746 15073731535 016001 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _changes:
.. The recent changes from the top-level file:
.. include:: ../CHANGES.rst
:end-before: endchangesinclude
.. Older changes here:
.. _changes_521:
Version 5.2.1 โ 2020-07-23
--------------------------
- The dark mode HTML report still used light colors for the context listing,
making them unreadable (`issue 1009`_). This is now fixed.
- The time stamp on the HTML report now includes the time zone. Thanks, Xie
Yanbo (`pull request 960`_).
.. _pull request 960: https://github.com/nedbat/coveragepy/pull/960
.. _issue 1009: https://github.com/nedbat/coveragepy/issues/1009
.. _changes_52:
Version 5.2 โ 2020-07-05
------------------------
- The HTML report has been redesigned by Vince Salvino. There is now a dark
mode, the code text is larger, and system sans serif fonts are used, in
addition to other small changes (`issue 858`_ and `pull request 931`_).
- The ``coverage report`` and ``coverage html`` commands now accept a
``--precision`` option to control the number of decimal points displayed.
Thanks, Teake Nutma (`pull request 982`_).
- The ``coverage report`` and ``coverage html`` commands now accept a
``--no-skip-covered`` option to negate ``--skip-covered``. Thanks, Anthony
Sottile (`issue 779`_ and `pull request 932`_).
- The ``--skip-empty`` option is now available for the XML report, closing
`issue 976`_.
- The ``coverage report`` command now accepts a ``--sort`` option to specify
how to sort the results. Thanks, Jerin Peter George (`pull request 1005`_).
- If coverage fails due to the coverage total not reaching the ``--fail-under``
value, it will now print a message making the condition clear. Thanks,
Naveen Yadav (`pull request 977`_).
- TOML configuration files with non-ASCII characters would cause errors on
Windows (`issue 990`_). This is now fixed.
- The output of ``--debug=trace`` now includes information about how the
``--source`` option is being interpreted, and the module names being
considered.
.. _pull request 931: https://github.com/nedbat/coveragepy/pull/931
.. _pull request 932: https://github.com/nedbat/coveragepy/pull/932
.. _pull request 977: https://github.com/nedbat/coveragepy/pull/977
.. _pull request 982: https://github.com/nedbat/coveragepy/pull/982
.. _pull request 1005: https://github.com/nedbat/coveragepy/pull/1005
.. _issue 779: https://github.com/nedbat/coveragepy/issues/779
.. _issue 858: https://github.com/nedbat/coveragepy/issues/858
.. _issue 976: https://github.com/nedbat/coveragepy/issues/976
.. _issue 990: https://github.com/nedbat/coveragepy/issues/990
.. _changes_51:
Version 5.1 โ 2020-04-12
------------------------
- The JSON report now includes counts of covered and missing branches. Thanks,
Salvatore Zagaria.
- On Python 3.8, try-finally-return reported wrong branch coverage with
decorated async functions (`issue 964`_). This is now fixed. Thanks, Kjell
Braden.
- The :meth:`~coverage.Coverage.get_option` and
:meth:`~coverage.Coverage.set_option` methods can now manipulate the
``[paths]`` configuration setting. Thanks to Bernรกt Gรกbor for the fix for
`issue 967`_.
.. _issue 964: https://github.com/nedbat/coveragepy/issues/964
.. _issue 967: https://github.com/nedbat/coveragepy/issues/967
.. _changes_504:
Version 5.0.4 โ 2020-03-16
--------------------------
- If using the ``[run] relative_files`` setting, the XML report will use
relative files in the ```` elements indicating the location of source
code. Closes `issue 948`_.
- The textual summary report could report missing lines with negative line
numbers on PyPy3 7.1 (`issue 943`_). This is now fixed.
- Windows wheels for Python 3.8 were incorrectly built, but are now fixed.
(`issue 949`_)
- Updated Python 3.9 support to 3.9a4.
- HTML reports couldn't be sorted if localStorage wasn't available. This is now
fixed: sorting works even though the sorting setting isn't retained. (`issue
944`_ and `pull request 945`_). Thanks, Abdeali Kothari.
.. _issue 943: https://github.com/nedbat/coveragepy/issues/943
.. _issue 944: https://github.com/nedbat/coveragepy/issues/944
.. _pull request 945: https://github.com/nedbat/coveragepy/pull/945
.. _issue 948: https://github.com/nedbat/coveragepy/issues/948
.. _issue 949: https://github.com/nedbat/coveragepy/issues/949
.. _changes_503:
Version 5.0.3 โ 2020-01-12
--------------------------
- A performance improvement in 5.0.2 didn't work for test suites that changed
directory before combining data, causing "Couldn't use data file: no such
table: meta" errors (`issue 916`_). This is now fixed.
- Coverage could fail to run your program with some form of "ModuleNotFound" or
"ImportError" trying to import from the current directory. This would happen
if coverage had been packaged into a zip file (for example, on Windows), or
was found indirectly (for example, by pyenv-virtualenv). A number of
different scenarios were described in `issue 862`_ which is now fixed. Huge
thanks to Agbonze O. Jeremiah for reporting it, and Alexander Waters and
George-Cristian Bรฎrzan for protracted debugging sessions.
- Added the "premain" debug option.
- Added SQLite compile-time options to the "debug sys" output.
.. _issue 862: https://github.com/nedbat/coveragepy/issues/862
.. _issue 916: https://github.com/nedbat/coveragepy/issues/916
.. _changes_502:
Version 5.0.2 โ 2020-01-05
--------------------------
- Programs that used multiprocessing and changed directories would fail under
coverage. This is now fixed (`issue 890`_). A side effect is that debug
information about the config files read now shows absolute paths to the
files.
- When running programs as modules (``coverage run -m``) with ``--source``,
some measured modules were imported before coverage starts. This resulted in
unwanted warnings ("Already imported a file that will be measured") and a
reduction in coverage totals (`issue 909`_). This is now fixed.
- If no data was collected, an exception about "No data to report" could happen
instead of a 0% report being created (`issue 884`_). This is now fixed.
- The handling of source files with non-encodable file names has changed.
Previously, if a file name could not be encoded as UTF-8, an error occurred,
as described in `issue 891`_. Now, those files will not be measured, since
their data would not be recordable.
- A new warning ("dynamic-conflict") is issued if two mechanisms are trying to
change the dynamic context. Closes `issue 901`_.
- ``coverage run --debug=sys`` would fail with an AttributeError. This is now
fixed (`issue 907`_).
.. _issue 884: https://github.com/nedbat/coveragepy/issues/884
.. _issue 890: https://github.com/nedbat/coveragepy/issues/890
.. _issue 891: https://github.com/nedbat/coveragepy/issues/891
.. _issue 901: https://github.com/nedbat/coveragepy/issues/901
.. _issue 907: https://github.com/nedbat/coveragepy/issues/907
.. _issue 909: https://github.com/nedbat/coveragepy/issues/909
.. _changes_501:
Version 5.0.1 โ 2019-12-22
--------------------------
- If a 4.x data file is the cause of a "file is not a database" error, then use
a more specific error message, "Looks like a coverage 4.x data file, are you
mixing versions of coverage?" Helps diagnose the problems described in
`issue 886`_.
- Measurement contexts and relative file names didn't work together, as
reported in `issue 899`_ and `issue 900`_. This is now fixed, thanks to
David Szotten.
- When using ``coverage run --concurrency=multiprocessing``, all data files
should be named with parallel-ready suffixes. 5.0 mistakenly named the main
process' file with no suffix when using ``--append``. This is now fixed,
closing `issue 880`_.
- Fixed a problem on Windows when the current directory is changed to a
different drive (`issue 895`_). Thanks, Olivier Grisel.
- Updated Python 3.9 support to 3.9a2.
.. _issue 880: https://github.com/nedbat/coveragepy/issues/880
.. _issue 886: https://github.com/nedbat/coveragepy/issues/886
.. _issue 895: https://github.com/nedbat/coveragepy/issues/895
.. _issue 899: https://github.com/nedbat/coveragepy/issues/899
.. _issue 900: https://github.com/nedbat/coveragepy/issues/900
.. _changes_50:
Version 5.0 โ 2019-12-14
------------------------
Nothing new beyond 5.0b2.
A summary of major changes in 5.0 since 4.5.x is in see :ref:`whatsnew5x`.
.. _changes_50b2:
Version 5.0b2 โ 2019-12-08
--------------------------
- An experimental ``[run] relative_files`` setting tells coverage to store
relative file names in the data file. This makes it easier to run tests in
one (or many) environments, and then report in another. It has not had much
real-world testing, so it may change in incompatible ways in the future.
- When constructing a :class:`coverage.Coverage` object, `data_file` can be
specified as None to prevent writing any data file at all. In previous
versions, an explicit `data_file=None` argument would use the default of
".coverage". Fixes `issue 871`_.
- Python files run with ``-m`` now have ``__spec__`` defined properly. This
fixes `issue 745`_ (about not being able to run unittest tests that spawn
subprocesses), and `issue 838`_, which described the problem directly.
- The ``[paths]`` configuration section is now ordered. If you specify more
than one list of patterns, the first one that matches will be used. Fixes
`issue 649`_.
- The :func:`.coverage.numbits.register_sqlite_functions` function now also
registers `numbits_to_nums` for use in SQLite queries. Thanks, Simon
Willison.
- Python 3.9a1 is supported.
- Coverage.py has a mascot: :ref:`Sleepy Snake `.
.. _issue 649: https://github.com/nedbat/coveragepy/issues/649
.. _issue 745: https://github.com/nedbat/coveragepy/issues/745
.. _issue 838: https://github.com/nedbat/coveragepy/issues/838
.. _issue 871: https://github.com/nedbat/coveragepy/issues/871
.. _changes_50b1:
Version 5.0b1 โ 2019-11-11
--------------------------
- The HTML and textual reports now have a ``--skip-empty`` option that skips
files with no statements, notably ``__init__.py`` files. Thanks, Reya B.
- Configuration can now be read from `TOML`_ files. This requires installing
coverage.py with the ``[toml]`` extra. The standard "pyproject.toml" file
will be read automatically if no other configuration file is found, with
settings in the ``[tool.coverage.]`` namespace. Thanks to Frazer McLean for
implementation and persistence. Finishes `issue 664`_.
- The ``[run] note`` setting has been deprecated. Using it will result in a
warning, and the note will not be written to the data file. The
corresponding :class:`.CoverageData` methods have been removed.
- The HTML report has been reimplemented (no more table around the source
code). This allowed for a better presentation of the context information,
hopefully resolving `issue 855`_.
- Added sqlite3 module version information to ``coverage debug sys`` output.
- Asking the HTML report to show contexts (``[html] show_contexts=True`` or
``coverage html --show-contexts``) will issue a warning if there were no
contexts measured (`issue 851`_).
.. _TOML: https://toml.io/
.. _issue 664: https://github.com/nedbat/coveragepy/issues/664
.. _issue 851: https://github.com/nedbat/coveragepy/issues/851
.. _issue 855: https://github.com/nedbat/coveragepy/issues/855
.. _changes_50a8:
Version 5.0a8 โ 2019-10-02
--------------------------
- The :class:`.CoverageData` API has changed how queries are limited to
specific contexts. Now you use :meth:`.CoverageData.set_query_context` to
set a single exact-match string, or :meth:`.CoverageData.set_query_contexts`
to set a list of regular expressions to match contexts. This changes the
command-line ``--contexts`` option to use regular expressions instead of
filename-style wildcards.
.. _changes_50a7:
Version 5.0a7 โ 2019-09-21
--------------------------
- Data can now be "reported" in JSON format, for programmatic use, as requested
in `issue 720`_. The new ``coverage json`` command writes raw and summarized
data to a JSON file. Thanks, Matt Bachmann.
- Dynamic contexts are now supported in the Python tracer, which is important
for PyPy users. Closes `issue 846`_.
- The compact line number representation introduced in 5.0a6 is called a
"numbits." The :mod:`coverage.numbits` module provides functions for working
with them.
- The reporting methods used to permanently apply their arguments to the
configuration of the Coverage object. Now they no longer do. The arguments
affect the operation of the method, but do not persist.
- A class named "test_something" no longer confuses the ``test_function``
dynamic context setting. Fixes `issue 829`_.
- Fixed an unusual tokenizing issue with backslashes in comments. Fixes
`issue 822`_.
- ``debug=plugin`` didn't properly support configuration or dynamic context
plugins, but now it does, closing `issue 834`_.
.. _issue 720: https://github.com/nedbat/coveragepy/issues/720
.. _issue 822: https://github.com/nedbat/coveragepy/issues/822
.. _issue 834: https://github.com/nedbat/coveragepy/issues/834
.. _issue 829: https://github.com/nedbat/coveragepy/issues/829
.. _issue 846: https://github.com/nedbat/coveragepy/issues/846
.. _changes_50a6:
Version 5.0a6 โ 2019-07-16
--------------------------
- Reporting on contexts. Big thanks to Stephan Richter and Albertas Agejevas
for the contribution.
- The ``--contexts`` option is available on the ``report`` and ``html``
commands. It's a comma-separated list of shell-style wildcards, selecting
the contexts to report on. Only contexts matching one of the wildcards
will be included in the report.
- The ``--show-contexts`` option for the ``html`` command adds context
information to each covered line. Hovering over the "ctx" marker at the
end of the line reveals a list of the contexts that covered the line.
- Database changes:
- Line numbers are now stored in a much more compact way. For each file and
context, a single binary string is stored with a bit per line number. This
greatly improves memory use, but makes ad-hoc use difficult.
- Dynamic contexts with no data are no longer written to the database.
- SQLite data storage is now faster. There's no longer a reason to keep the
JSON data file code, so it has been removed.
- Changes to the :class:`.CoverageData` interface:
- The new :meth:`.CoverageData.dumps` method serializes the data to a string,
and a corresponding :meth:`.CoverageData.loads` method reconstitutes this
data. The format of the data string is subject to change at any time, and
so should only be used between two installations of the same version of
coverage.py.
- The :class:`CoverageData constructor<.CoverageData>` has a new
argument, `no_disk` (default: False). Setting it to True prevents writing
any data to the disk. This is useful for transient data objects.
- Added the class method :meth:`.Coverage.current` to get the latest started
Coverage instance.
- Multiprocessing support in Python 3.8 was broken, but is now fixed. Closes
`issue 828`_.
- Error handling during reporting has changed slightly. All reporting methods
now behave the same. The ``--ignore-errors`` option keeps errors from
stopping the reporting, but files that couldn't parse as Python will always
be reported as warnings. As with other warnings, you can suppress them with
the ``[run] disable_warnings`` configuration setting.
- Coverage.py no longer fails if the user program deletes its current
directory. Fixes `issue 806`_. Thanks, Dan Hemberger.
- The scrollbar markers in the HTML report now accurately show the highlighted
lines, regardless of what categories of line are highlighted.
- The hack to accommodate ShiningPanda_ looking for an obsolete internal data
file has been removed, since ShiningPanda 0.22 fixed it four years ago.
- The deprecated `Reporter.file_reporters` property has been removed.
.. _ShiningPanda: https://plugins.jenkins.io/shiningpanda/
.. _issue 806: https://github.com/nedbat/coveragepy/pull/806
.. _issue 828: https://github.com/nedbat/coveragepy/issues/828
.. _changes_50a5:
Version 5.0a5 โ 2019-05-07
--------------------------
- Drop support for Python 3.4
- Dynamic contexts can now be set two new ways, both thanks to Justas
Sadzeviฤius.
- A plugin can implement a ``dynamic_context`` method to check frames for
whether a new context should be started. See
:ref:`dynamic_context_plugins` for more details.
- Another tool (such as a test runner) can use the new
:meth:`.Coverage.switch_context` method to explicitly change the context.
- The ``dynamic_context = test_function`` setting now works with Python 2
old-style classes, though it only reports the method name, not the class it
was defined on. Closes `issue 797`_.
- ``fail_under`` values more than 100 are reported as errors. Thanks to Mike
Fiedler for closing `issue 746`_.
- The "missing" values in the text output are now sorted by line number, so
that missing branches are reported near the other lines they affect. The
values used to show all missing lines, and then all missing branches.
- Access to the SQLite database used for data storage is now thread-safe.
Thanks, Stephan Richter. This closes `issue 702`_.
- Combining data stored in SQLite is now about twice as fast, fixing `issue
761`_. Thanks, Stephan Richter.
- The ``filename`` attribute on :class:`.CoverageData` objects has been made
private. You can use the ``data_filename`` method to get the actual file
name being used to store data, and the ``base_filename`` method to get the
original filename before parallelizing suffixes were added. This is part of
fixing `issue 708`_.
- Line numbers in the HTML report now align properly with source lines, even
when Chrome's minimum font size is set, fixing `issue 748`_. Thanks Wen Ye.
.. _issue 702: https://github.com/nedbat/coveragepy/issues/702
.. _issue 708: https://github.com/nedbat/coveragepy/issues/708
.. _issue 746: https://github.com/nedbat/coveragepy/issues/746
.. _issue 748: https://github.com/nedbat/coveragepy/issues/748
.. _issue 761: https://github.com/nedbat/coveragepy/issues/761
.. _issue 797: https://github.com/nedbat/coveragepy/issues/797
.. _changes_50a4:
Version 5.0a4 โ 2018-11-25
--------------------------
- You can specify the command line to run your program with the ``[run]
command_line`` configuration setting, as requested in `issue 695`_.
- Coverage will create directories as needed for the data file if they don't
exist, closing `issue 721`_.
- The ``coverage run`` command has always adjusted the first entry in sys.path,
to properly emulate how Python runs your program. Now this adjustment is
skipped if sys.path[0] is already different than Python's default. This
fixes `issue 715`_.
- Improvements to context support:
- The "no such table: meta" error is fixed.: `issue 716`_.
- Combining data files is now much faster.
- Python 3.8 (as of today!) passes all tests.
.. _issue 695: https://github.com/nedbat/coveragepy/issues/695
.. _issue 715: https://github.com/nedbat/coveragepy/issues/715
.. _issue 716: https://github.com/nedbat/coveragepy/issues/716
.. _issue 721: https://github.com/nedbat/coveragepy/issues/721
.. _changes_50a3:
Version 5.0a3 โ 2018-10-06
--------------------------
- Context support: static contexts let you specify a label for a coverage run,
which is recorded in the data, and retained when you combine files. See
:ref:`contexts` for more information.
- Dynamic contexts: specifying ``[run] dynamic_context = test_function`` in the
config file will record the test function name as a dynamic context during
execution. This is the core of "Who Tests What" (`issue 170`_). Things to
note:
- There is no reporting support yet. Use SQLite to query the .coverage file
for information. Ideas are welcome about how reporting could be extended
to use this data.
- There's a noticeable slow-down before any test is run.
- Data files will now be roughly N times larger, where N is the number of
tests you have. Combining data files is therefore also N times slower.
- No other values for ``dynamic_context`` are recognized yet. Let me know
what else would be useful. I'd like to use a pytest plugin to get better
information directly from pytest, for example.
.. _issue 170: https://github.com/nedbat/coveragepy/issues/170
- Environment variable substitution in configuration files now supports two
syntaxes for controlling the behavior of undefined variables: if ``VARNAME``
is not defined, ``${VARNAME?}`` will raise an error, and ``${VARNAME-default
value}`` will use "default value".
- Partial support for Python 3.8, which has not yet released an alpha. Fixes
`issue 707`_ and `issue 714`_.
.. _issue 707: https://github.com/nedbat/coveragepy/issues/707
.. _issue 714: https://github.com/nedbat/coveragepy/issues/714
.. _changes_50a2:
Version 5.0a2 โ 2018-09-03
--------------------------
- Coverage's data storage has changed. In version 4.x, .coverage files were
basically JSON. Now, they are SQLite databases. This means the data file
can be created earlier than it used to. A large amount of code was
refactored to support this change.
- Because the data file is created differently than previous releases, you
may need ``parallel=true`` where you didn't before.
- The old data format is still available (for now) by setting the environment
variable ``COVERAGE_STORAGE=json``. Please tell me if you think you need to
keep the JSON format.
- The database schema is guaranteed to change in the future, to support new
features. I'm looking for opinions about making the schema part of the
public API to coverage.py or not.
- Development moved from `Bitbucket`_ to `GitHub`_.
- HTML files no longer have trailing and extra white space.
- The sort order in the HTML report is stored in local storage rather than
cookies, closing `issue 611`_. Thanks, Federico Bond.
- pickle2json, for converting v3 data files to v4 data files, has been removed.
.. _Bitbucket: https://bitbucket.org
.. _GitHub: https://github.com/nedbat/coveragepy
.. _issue 611: https://github.com/nedbat/coveragepy/issues/611
.. _changes_50a1:
Version 5.0a1 โ 2018-06-05
--------------------------
- Coverage.py no longer supports Python 2.6 or 3.3.
- The location of the configuration file can now be specified with a
``COVERAGE_RCFILE`` environment variable, as requested in `issue 650`_.
- Namespace packages are supported on Python 3.7, where they used to cause
TypeErrors about path being None. Fixes `issue 700`_.
- A new warning (``already-imported``) is issued if measurable files have
already been imported before coverage.py started measurement. See
:ref:`cmd_warnings` for more information.
- Running coverage many times for small runs in a single process should be
faster, closing `issue 625`_. Thanks, David MacIver.
- Large HTML report pages load faster. Thanks, Pankaj Pandey.
.. _issue 625: https://github.com/nedbat/coveragepy/issues/625
.. _issue 650: https://github.com/nedbat/coveragepy/issues/650
.. _issue 700: https://github.com/nedbat/coveragepy/issues/700
.. _changes_454:
Version 4.5.4 โ 2019-07-29
--------------------------
- Multiprocessing support in Python 3.8 was broken, but is now fixed. Closes
`issue 828`_.
.. _issue 828: https://github.com/nedbat/coveragepy/issues/828
.. _changes_453:
Version 4.5.3 โ 2019-03-09
--------------------------
- Only packaging metadata changes.
.. _changes_452:
Version 4.5.2 โ 2018-11-12
--------------------------
- Namespace packages are supported on Python 3.7, where they used to cause
TypeErrors about path being None. Fixes `issue 700`_.
- Python 3.8 (as of today!) passes all tests. Fixes `issue 707`_ and
`issue 714`_.
- Development moved from `Bitbucket`_ to `GitHub`_.
.. _issue 700: https://github.com/nedbat/coveragepy/issues/700
.. _issue 707: https://github.com/nedbat/coveragepy/issues/707
.. _issue 714: https://github.com/nedbat/coveragepy/issues/714
.. _Bitbucket: https://bitbucket.org
.. _GitHub: https://github.com/nedbat/coveragepy
.. _changes_451:
Version 4.5.1 โ 2018-02-10
--------------------------
- Now that 4.5 properly separated the ``[run] omit`` and ``[report] omit``
settings, an old bug has become apparent. If you specified a package name
for ``[run] source``, then omit patterns weren't matched inside that package.
This bug (`issue 638`_) is now fixed.
- On Python 3.7, reporting about a decorated function with no body other than a
docstring would crash coverage.py with an IndexError (`issue 640`_). This is
now fixed.
- Configurer plugins are now reported in the output of ``--debug=sys``.
.. _issue 638: https://github.com/nedbat/coveragepy/issues/638
.. _issue 640: https://github.com/nedbat/coveragepy/issues/640
.. _changes_45:
Version 4.5 โ 2018-02-03
------------------------
- A new kind of plugin is supported: configurers are invoked at start-up to
allow more complex configuration than the .coveragerc file can easily do.
See :ref:`api_plugin` for details. This solves the complex configuration
problem described in `issue 563`_.
- The ``fail_under`` option can now be a float. Note that you must specify the
``[report] precision`` configuration option for the fractional part to be
used. Thanks to Lars Hupfeldt Nielsen for help with the implementation.
Fixes `issue 631`_.
- The ``include`` and ``omit`` options can be specified for both the ``[run]``
and ``[report]`` phases of execution. 4.4.2 introduced some incorrect
interactions between those phases, where the options for one were confused
for the other. This is now corrected, fixing `issue 621`_ and `issue 622`_.
Thanks to Daniel Hahler for seeing more clearly than I could.
- The ``coverage combine`` command used to always overwrite the data file, even
when no data had been read from apparently combinable files. Now, an error
is raised if we thought there were files to combine, but in fact none of them
could be used. Fixes `issue 629`_.
- The ``coverage combine`` command could get confused about path separators
when combining data collected on Windows with data collected on Linux, as
described in `issue 618`_. This is now fixed: the result path always uses
the path separator specified in the ``[paths]`` result.
- On Windows, the HTML report could fail when source trees are deeply nested,
due to attempting to create HTML filenames longer than the 250-character
maximum. Now filenames will never get much larger than 200 characters,
fixing `issue 627`_. Thanks to Alex Sandro for helping with the fix.
.. _issue 563: https://github.com/nedbat/coveragepy/issues/563
.. _issue 618: https://github.com/nedbat/coveragepy/issues/618
.. _issue 621: https://github.com/nedbat/coveragepy/issues/621
.. _issue 622: https://github.com/nedbat/coveragepy/issues/622
.. _issue 627: https://github.com/nedbat/coveragepy/issues/627
.. _issue 629: https://github.com/nedbat/coveragepy/issues/629
.. _issue 631: https://github.com/nedbat/coveragepy/issues/631
.. _changes_442:
Version 4.4.2 โ 2017-11-05
--------------------------
- Support for Python 3.7. In some cases, class and module docstrings are no
longer counted in statement totals, which could slightly change your total
results.
- Specifying both ``--source`` and ``--include`` no longer silently ignores the
include setting, instead it displays a warning. Thanks, Loรฏc Dachary. Closes
`issue 265`_ and `issue 101`_.
- Fixed a race condition when saving data and multiple threads are tracing
(`issue 581`_). It could produce a "dictionary changed size during iteration"
RuntimeError. I believe this mostly but not entirely fixes the race
condition. A true fix would likely be too expensive. Thanks, Peter Baughman
for the debugging, and Olivier Grisel for the fix with tests.
- Configuration values which are file paths will now apply tilde-expansion,
closing `issue 589`_.
- Now secondary config files like tox.ini and setup.cfg can be specified
explicitly, and prefixed sections like `[coverage:run]` will be read. Fixes
`issue 588`_.
- Be more flexible about the command name displayed by help, fixing
`issue 600`_. Thanks, Ben Finney.
.. _issue 101: https://github.com/nedbat/coveragepy/issues/101
.. _issue 581: https://github.com/nedbat/coveragepy/issues/581
.. _issue 588: https://github.com/nedbat/coveragepy/issues/588
.. _issue 589: https://github.com/nedbat/coveragepy/issues/589
.. _issue 600: https://github.com/nedbat/coveragepy/issues/600
.. _changes_441:
Version 4.4.1 โ 2017-05-14
--------------------------
- No code changes: just corrected packaging for Python 2.7 Linux wheels.
.. _changes_44:
Version 4.4 โ 2017-05-07
------------------------
- Reports could produce the wrong file names for packages, reporting ``pkg.py``
instead of the correct ``pkg/__init__.py``. This is now fixed. Thanks, Dirk
Thomas.
- XML reports could produce ```` and ```` lines that together
didn't specify a valid source file path. This is now fixed. (`issue 526`_)
- Namespace packages are no longer warned as having no code. (`issue 572`_)
- Code that uses ``sys.settrace(sys.gettrace())`` in a file that wasn't being
coverage-measured would prevent correct coverage measurement in following
code. An example of this was running doctests programmatically. This is now
fixed. (`issue 575`_)
- Errors printed by the ``coverage`` command now go to stderr instead of
stdout.
- Running ``coverage xml`` in a directory named with non-ASCII characters would
fail under Python 2. This is now fixed. (`issue 573`_)
.. _issue 526: https://github.com/nedbat/coveragepy/issues/526
.. _issue 572: https://github.com/nedbat/coveragepy/issues/572
.. _issue 573: https://github.com/nedbat/coveragepy/issues/573
.. _issue 575: https://github.com/nedbat/coveragepy/issues/575
Version 4.4b1 โ 2017-04-04
--------------------------
- Some warnings can now be individually disabled. Warnings that can be
disabled have a short name appended. The ``[run] disable_warnings`` setting
takes a list of these warning names to disable. Closes both `issue 96`_ and
`issue 355`_.
- The XML report now includes attributes from version 4 of the Cobertura XML
format, fixing `issue 570`_.
- In previous versions, calling a method that used collected data would prevent
further collection. For example, `save()`, `report()`, `html_report()`, and
others would all stop collection. An explicit `start()` was needed to get it
going again. This is no longer true. Now you can use the collected data and
also continue measurement. Both `issue 79`_ and `issue 448`_ described this
problem, and have been fixed.
- Plugins can now find un-executed files if they choose, by implementing the
`find_executable_files` method. Thanks, Emil Madsen.
- Minimal IronPython support. You should be able to run IronPython programs
under ``coverage run``, though you will still have to do the reporting phase
with CPython.
- Coverage.py has long had a special hack to support CPython's need to measure
the coverage of the standard library tests. This code was not installed by
kitted versions of coverage.py. Now it is.
.. _issue 79: https://github.com/nedbat/coveragepy/issues/79
.. _issue 96: https://github.com/nedbat/coveragepy/issues/96
.. _issue 355: https://github.com/nedbat/coveragepy/issues/355
.. _issue 448: https://github.com/nedbat/coveragepy/issues/448
.. _issue 570: https://github.com/nedbat/coveragepy/issues/570
.. _changes_434:
Version 4.3.4 โ 2017-01-17
--------------------------
- Fixing 2.6 in version 4.3.3 broke other things, because the too-tricky
exception wasn't properly derived from Exception, described in `issue 556`_.
A newb mistake; it hasn't been a good few days.
.. _issue 556: https://github.com/nedbat/coveragepy/issues/556
.. _changes_433:
Version 4.3.3 โ 2017-01-17
--------------------------
- Python 2.6 support was broken due to a testing exception imported for the
benefit of the coverage.py test suite. Properly conditionalizing it fixed
`issue 554`_ so that Python 2.6 works again.
.. _issue 554: https://github.com/nedbat/coveragepy/issues/554
.. _changes_432:
Version 4.3.2 โ 2017-01-16
--------------------------
- Using the ``--skip-covered`` option on an HTML report with 100% coverage
would cause a "No data to report" error, as reported in `issue 549`_. This is
now fixed; thanks, Loรฏc Dachary.
- If-statements can be optimized away during compilation, for example,
``if 0:`` or ``if __debug__:``. Coverage.py had problems properly
understanding these statements which existed in the source, but not in the
compiled bytecode. This problem, reported in `issue 522`_, is now fixed.
- If you specified ``--source`` as a directory, then coverage.py would look for
importable Python files in that directory, and could identify ones that had
never been executed at all. But if you specified it as a package name, that
detection wasn't performed. Now it is, closing `issue 426`_. Thanks to Loรฏc
Dachary for the fix.
- If you started and stopped coverage measurement thousands of times in your
process, you could crash Python with a "Fatal Python error: deallocating
None" error. This is now fixed. Thanks to Alex Groce for the bug report.
- On PyPy, measuring coverage in subprocesses could produce a warning: "Trace
function changed, measurement is likely wrong: None". This was spurious, and
has been suppressed.
- Previously, coverage.py couldn't start on Jython, due to that implementation
missing the multiprocessing module (`issue 551`_). This problem has now been
fixed. Also, `issue 322`_ about not being able to invoke coverage
conveniently, seems much better: ``jython -m coverage run myprog.py`` works
properly.
- Let's say you ran the HTML report over and over again in the same output
directory, with ``--skip-covered``. And imagine due to your heroic
test-writing efforts, a file just achieved the goal of 100% coverage. With
coverage.py 4.3, the old HTML file with the less-than-100% coverage would be
left behind. This file is now properly deleted.
.. _issue 322: https://github.com/nedbat/coveragepy/issues/322
.. _issue 426: https://github.com/nedbat/coveragepy/issues/426
.. _issue 522: https://github.com/nedbat/coveragepy/issues/522
.. _issue 549: https://github.com/nedbat/coveragepy/issues/549
.. _issue 551: https://github.com/nedbat/coveragepy/issues/551
.. _changes_431:
Version 4.3.1 โ 2016-12-28
--------------------------
- Some environments couldn't install 4.3, as described in `issue 540`_. This is
now fixed.
- The check for conflicting ``--source`` and ``--include`` was too simple in a
few different ways, breaking a few perfectly reasonable use cases, described
in `issue 541`_. The check has been reverted while we re-think the fix for
`issue 265`_.
.. _issue 540: https://github.com/nedbat/coveragepy/issues/540
.. _issue 541: https://github.com/nedbat/coveragepy/issues/541
.. _changes_43:
Version 4.3 โ 2016-12-27
------------------------
Special thanks to **Loรฏc Dachary**, who took an extraordinary interest in
coverage.py and contributed a number of improvements in this release.
- Subprocesses that are measured with `automatic subprocess measurement`_ used
to read in any pre-existing data file. This meant data would be incorrectly
carried forward from run to run. Now those files are not read, so each
subprocess only writes its own data. Fixes `issue 510`_.
- The ``coverage combine`` command will now fail if there are no data files to
combine. The combine changes in 4.2 meant that multiple combines could lose
data, leaving you with an empty .coverage data file. Fixes
`issue 525`_, `issue 412`_, `issue 516`_, and probably `issue 511`_.
- Coverage.py wouldn't execute `sys.excepthook`_ when an exception happened in
your program. Now it does, thanks to Andrew Hoos. Closes `issue 535`_.
- Branch coverage fixes:
- Branch coverage could misunderstand a finally clause on a try block that
never continued on to the following statement, as described in `issue
493`_. This is now fixed. Thanks to Joe Doherty for the report and Loรฏc
Dachary for the fix.
- A while loop with a constant condition (while True) and a continue
statement would be mis-analyzed, as described in `issue 496`_. This is now
fixed, thanks to a bug report by Eli Skeggs and a fix by Loรฏc Dachary.
- While loops with constant conditions that were never executed could result
in a non-zero coverage report. Artem Dayneko reported this in `issue
502`_, and Loรฏc Dachary provided the fix.
- The HTML report now supports a ``--skip-covered`` option like the other
reporting commands. Thanks, Loรฏc Dachary for the implementation, closing
`issue 433`_.
- Options can now be read from a tox.ini file, if any. Like setup.cfg, sections
are prefixed with "coverage:", so ``[run]`` options will be read from the
``[coverage:run]`` section of tox.ini. Implements part of `issue 519`_.
Thanks, Stephen Finucane.
- Specifying both ``--source`` and ``--include`` no longer silently ignores the
include setting, instead it fails with a message. Thanks, Nathan Land and
Loรฏc Dachary. Closes `issue 265`_.
- The ``Coverage.combine`` method has a new parameter, ``strict=False``, to
support failing if there are no data files to combine.
- When forking subprocesses, the coverage data files would have the same random
number appended to the file name. This didn't cause problems, because the
file names had the process id also, making collisions (nearly) impossible.
But it was disconcerting. This is now fixed.
- The text report now properly sizes headers when skipping some files, fixing
`issue 524`_. Thanks, Anthony Sottile and Loรฏc Dachary.
- Coverage.py can now search .pex files for source, just as it can .zip and
.egg. Thanks, Peter Ebden.
- Data files are now about 15% smaller.
- Improvements in the ``[run] debug`` setting:
- The "dataio" debug setting now also logs when data files are deleted during
combining or erasing.
- A new debug option, "multiproc", for logging the behavior of
``concurrency=multiprocessing``.
- If you used the debug options "config" and "callers" together, you'd get a
call stack printed for every line in the multi-line config output. This is
now fixed.
- Fixed an unusual bug involving multiple coding declarations affecting code
containing code in multi-line strings: `issue 529`_.
- Coverage.py will no longer be misled into thinking that a plain file is a
package when interpreting ``--source`` options. Thanks, Cosimo Lupo.
- If you try to run a non-Python file with coverage.py, you will now get a more
useful error message. `Issue 514`_.
- The default pragma regex changed slightly, but this will only matter to you
if you are deranged and use mixed-case pragmas.
- Deal properly with non-ASCII file names in an ASCII-only world, `issue 533`_.
- Programs that set Unicode configuration values could cause UnicodeErrors when
generating HTML reports. Pytest-cov is one example. This is now fixed.
- Prevented deprecation warnings from configparser that happened in some
circumstances, closing `issue 530`_.
- Corrected the name of the jquery.ba-throttle-debounce.js library. Thanks,
Ben Finney. Closes `issue 505`_.
- Testing against PyPy 5.6 and PyPy3 5.5.
- Switched to pytest from nose for running the coverage.py tests.
- Renamed AUTHORS.txt to CONTRIBUTORS.txt, since there are other ways to
contribute than by writing code. Also put the count of contributors into the
author string in setup.py, though this might be too cute.
.. _sys.excepthook: https://docs.python.org/3/library/sys.html#sys.excepthook
.. _issue 265: https://github.com/nedbat/coveragepy/issues/265
.. _issue 412: https://github.com/nedbat/coveragepy/issues/412
.. _issue 433: https://github.com/nedbat/coveragepy/issues/433
.. _issue 493: https://github.com/nedbat/coveragepy/issues/493
.. _issue 496: https://github.com/nedbat/coveragepy/issues/496
.. _issue 502: https://github.com/nedbat/coveragepy/issues/502
.. _issue 505: https://github.com/nedbat/coveragepy/issues/505
.. _issue 514: https://github.com/nedbat/coveragepy/issues/514
.. _issue 510: https://github.com/nedbat/coveragepy/issues/510
.. _issue 511: https://github.com/nedbat/coveragepy/issues/511
.. _issue 516: https://github.com/nedbat/coveragepy/issues/516
.. _issue 519: https://github.com/nedbat/coveragepy/issues/519
.. _issue 524: https://github.com/nedbat/coveragepy/issues/524
.. _issue 525: https://github.com/nedbat/coveragepy/issues/525
.. _issue 529: https://github.com/nedbat/coveragepy/issues/529
.. _issue 530: https://github.com/nedbat/coveragepy/issues/530
.. _issue 533: https://github.com/nedbat/coveragepy/issues/533
.. _issue 535: https://github.com/nedbat/coveragepy/issues/535
.. _changes_42:
Version 4.2 โ 2016-07-26
------------------------
- Since ``concurrency=multiprocessing`` uses subprocesses, options specified on
the coverage.py command line will not be communicated down to them. Only
options in the configuration file will apply to the subprocesses.
Previously, the options didn't apply to the subprocesses, but there was no
indication. Now it is an error to use ``--concurrency=multiprocessing`` and
other run-affecting options on the command line. This prevents
failures like those reported in `issue 495`_.
- Filtering the HTML report is now faster, thanks to Ville Skyttรค.
.. _issue 495: https://github.com/nedbat/coveragepy/issues/495
Version 4.2b1 โ 2016-07-04
--------------------------
Work from the PyCon 2016 Sprints!
- BACKWARD INCOMPATIBILITY: the ``coverage combine`` command now ignores an
existing ``.coverage`` data file. It used to include that file in its
combining. This caused confusing results, and extra tox "clean" steps. If
you want the old behavior, use the new ``coverage combine --append`` option.
- The ``concurrency`` option can now take multiple values, to support programs
using multiprocessing and another library such as eventlet. This is only
possible in the configuration file, not from the command line. The
configuration file is the only way for subprocesses to all run with the same
options. Fixes `issue 484`_. Thanks to Josh Williams for prototyping.
- Using a ``concurrency`` setting of ``multiprocessing`` now implies
``--parallel`` so that the main program is measured similarly to the
subprocesses.
- When using `automatic subprocess measurement`_, running coverage commands
would create spurious data files. This is now fixed, thanks to diagnosis and
testing by Dan Riti. Closes `issue 492`_.
- A new configuration option, ``report:sort``, controls what column of the
text report is used to sort the rows. Thanks to Dan Wandschneider, this
closes `issue 199`_.
- The HTML report has a more-visible indicator for which column is being
sorted. Closes `issue 298`_, thanks to Josh Williams.
- If the HTML report cannot find the source for a file, the message now
suggests using the ``-i`` flag to allow the report to continue. Closes
`issue 231`_, thanks, Nathan Land.
- When reports are ignoring errors, there's now a warning if a file cannot be
parsed, rather than being silently ignored. Closes `issue 396`_. Thanks,
Matthew Boehm.
- A new option for ``coverage debug`` is available: ``coverage debug config``
shows the current configuration. Closes `issue 454`_, thanks to Matthew
Boehm.
- Running coverage as a module (``python -m coverage``) no longer shows the
program name as ``__main__.py``. Fixes `issue 478`_. Thanks, Scott Belden.
- The `test_helpers` module has been moved into a separate pip-installable
package: `unittest-mixins`_.
.. _automatic subprocess measurement: https://coverage.readthedocs.io/en/latest/subprocess.html
.. _issue 199: https://github.com/nedbat/coveragepy/issues/199
.. _issue 231: https://github.com/nedbat/coveragepy/issues/231
.. _issue 298: https://github.com/nedbat/coveragepy/issues/298
.. _issue 396: https://github.com/nedbat/coveragepy/issues/396
.. _issue 454: https://github.com/nedbat/coveragepy/issues/454
.. _issue 478: https://github.com/nedbat/coveragepy/issues/478
.. _issue 484: https://github.com/nedbat/coveragepy/issues/484
.. _issue 492: https://github.com/nedbat/coveragepy/issues/492
.. _unittest-mixins: https://pypi.org/project/unittest-mixins/
.. _changes_41:
Version 4.1 โ 2016-05-21
------------------------
- The internal attribute `Reporter.file_reporters` was removed in 4.1b3. It
should have come has no surprise that there were third-party tools out there
using that attribute. It has been restored, but with a deprecation warning.
Version 4.1b3 โ 2016-05-10
--------------------------
- When running your program, execution can jump from an ``except X:`` line to
some other line when an exception other than ``X`` happens. This jump is no
longer considered a branch when measuring branch coverage.
- When measuring branch coverage, ``yield`` statements that were never resumed
were incorrectly marked as missing, as reported in `issue 440`_. This is now
fixed.
- During branch coverage of single-line callables like lambdas and generator
expressions, coverage.py can now distinguish between them never being called,
or being called but not completed. Fixes `issue 90`_, `issue 460`_ and
`issue 475`_.
- The HTML report now has a map of the file along the rightmost edge of the
page, giving an overview of where the missed lines are. Thanks, Dmitry
Shishov.
- The HTML report now uses different monospaced fonts, favoring Consolas over
Courier. Along the way, `issue 472`_ about not properly handling one-space
indents was fixed. The index page also has slightly different styling, to
try to make the clickable detail pages more apparent.
- Missing branches reported with ``coverage report -m`` will now say ``->exit``
for missed branches to the exit of a function, rather than a negative number.
Fixes `issue 469`_.
- ``coverage --help`` and ``coverage --version`` now mention which tracer is
installed, to help diagnose problems. The docs mention which features need
the C extension. (`issue 479`_)
- Officially support PyPy 5.1, which required no changes, just updates to the
docs.
- The `Coverage.report` function had two parameters with non-None defaults,
which have been changed. `show_missing` used to default to True, but now
defaults to None. If you had been calling `Coverage.report` without
specifying `show_missing`, you'll need to explicitly set it to True to keep
the same behavior. `skip_covered` used to default to False. It is now None,
which doesn't change the behavior. This fixes `issue 485`_.
- It's never been possible to pass a namespace module to one of the analysis
functions, but now at least we raise a more specific error message, rather
than getting confused. (`issue 456`_)
- The `coverage.process_startup` function now returns the `Coverage` instance
it creates, as suggested in `issue 481`_.
- Make a small tweak to how we compare threads, to avoid buggy custom
comparison code in thread classes. (`issue 245`_)
.. _issue 90: https://github.com/nedbat/coveragepy/issues/90
.. _issue 245: https://github.com/nedbat/coveragepy/issues/245
.. _issue 440: https://github.com/nedbat/coveragepy/issues/440
.. _issue 456: https://github.com/nedbat/coveragepy/issues/456
.. _issue 460: https://github.com/nedbat/coveragepy/issues/460
.. _issue 469: https://github.com/nedbat/coveragepy/issues/469
.. _issue 472: https://github.com/nedbat/coveragepy/issues/472
.. _issue 475: https://github.com/nedbat/coveragepy/issues/475
.. _issue 479: https://github.com/nedbat/coveragepy/issues/479
.. _issue 481: https://github.com/nedbat/coveragepy/issues/481
.. _issue 485: https://github.com/nedbat/coveragepy/issues/485
Version 4.1b2 โ 2016-01-23
--------------------------
- Problems with the new branch measurement in 4.1 beta 1 were fixed:
- Class docstrings were considered executable. Now they no longer are.
- ``yield from`` and ``await`` were considered returns from functions, since
they could transfer control to the caller. This produced unhelpful
"missing branch" reports in a number of circumstances. Now they no longer
are considered returns.
- In unusual situations, a missing branch to a negative number was reported.
This has been fixed, closing `issue 466`_.
- The XML report now produces correct package names for modules found in
directories specified with ``source=``. Fixes `issue 465`_.
- ``coverage report`` won't produce trailing white space.
.. _issue 465: https://github.com/nedbat/coveragepy/issues/465
.. _issue 466: https://github.com/nedbat/coveragepy/issues/466
Version 4.1b1 โ 2016-01-10
--------------------------
- Branch analysis has been rewritten: it used to be based on bytecode, but now
uses AST analysis. This has changed a number of things:
- More code paths are now considered runnable, especially in
``try``/``except`` structures. This may mean that coverage.py will
identify more code paths as uncovered. This could either raise or lower
your overall coverage number.
- Python 3.5's ``async`` and ``await`` keywords are properly supported,
fixing `issue 434`_.
- Some long-standing branch coverage bugs were fixed:
- `issue 129`_: functions with only a docstring for a body would
incorrectly report a missing branch on the ``def`` line.
- `issue 212`_: code in an ``except`` block could be incorrectly marked as
a missing branch.
- `issue 146`_: context managers (``with`` statements) in a loop or ``try``
block could confuse the branch measurement, reporting incorrect partial
branches.
- `issue 422`_: in Python 3.5, an actual partial branch could be marked as
complete.
- Pragmas to disable coverage measurement can now be used on decorator lines,
and they will apply to the entire function or class being decorated. This
implements the feature requested in `issue 131`_.
- Multiprocessing support is now available on Windows. Thanks, Rodrigue
Cloutier.
- Files with two encoding declarations are properly supported, fixing
`issue 453`_. Thanks, Max Linke.
- Non-ascii characters in regexes in the configuration file worked in 3.7, but
stopped working in 4.0. Now they work again, closing `issue 455`_.
- Form-feed characters would prevent accurate determination of the beginning of
statements in the rest of the file. This is now fixed, closing `issue 461`_.
.. _issue 129: https://github.com/nedbat/coveragepy/issues/129
.. _issue 131: https://github.com/nedbat/coveragepy/issues/131
.. _issue 146: https://github.com/nedbat/coveragepy/issues/146
.. _issue 212: https://github.com/nedbat/coveragepy/issues/212
.. _issue 422: https://github.com/nedbat/coveragepy/issues/422
.. _issue 434: https://github.com/nedbat/coveragepy/issues/434
.. _issue 453: https://github.com/nedbat/coveragepy/issues/453
.. _issue 455: https://github.com/nedbat/coveragepy/issues/455
.. _issue 461: https://github.com/nedbat/coveragepy/issues/461
.. _changes_403:
Version 4.0.3 โ 2015-11-24
--------------------------
- Fixed a mysterious problem that manifested in different ways: sometimes
hanging the process (`issue 420`_), sometimes making database connections
fail (`issue 445`_).
- The XML report now has correct ```` elements when using a
``--source=`` option somewhere besides the current directory. This fixes
`issue 439`_. Thanks, Arcadiy Ivanov.
- Fixed an unusual edge case of detecting source encodings, described in
`issue 443`_.
- Help messages that mention the command to use now properly use the actual
command name, which might be different than "coverage". Thanks to Ben
Finney, this closes `issue 438`_.
.. _issue 420: https://github.com/nedbat/coveragepy/issues/420
.. _issue 438: https://github.com/nedbat/coveragepy/issues/438
.. _issue 439: https://github.com/nedbat/coveragepy/issues/439
.. _issue 443: https://github.com/nedbat/coveragepy/issues/443
.. _issue 445: https://github.com/nedbat/coveragepy/issues/445
.. _changes_402:
Version 4.0.2 โ 2015-11-04
--------------------------
- More work on supporting unusually encoded source. Fixed `issue 431`_.
- Files or directories with non-ASCII characters are now handled properly,
fixing `issue 432`_.
- Setting a trace function with sys.settrace was broken by a change in 4.0.1,
as reported in `issue 436`_. This is now fixed.
- Officially support PyPy 4.0, which required no changes, just updates to the
docs.
.. _issue 431: https://github.com/nedbat/coveragepy/issues/431
.. _issue 432: https://github.com/nedbat/coveragepy/issues/432
.. _issue 436: https://github.com/nedbat/coveragepy/issues/436
.. _changes_401:
Version 4.0.1 โ 2015-10-13
--------------------------
- When combining data files, unreadable files will now generate a warning
instead of failing the command. This is more in line with the older
coverage.py v3.7.1 behavior, which silently ignored unreadable files.
Prompted by `issue 418`_.
- The --skip-covered option would skip reporting on 100% covered files, but
also skipped them when calculating total coverage. This was wrong, it should
only remove lines from the report, not change the final answer. This is now
fixed, closing `issue 423`_.
- In 4.0, the data file recorded a summary of the system on which it was run.
Combined data files would keep all of those summaries. This could lead to
enormous data files consisting of mostly repetitive useless information. That
summary is now gone, fixing `issue 415`_. If you want summary information,
get in touch, and we'll figure out a better way to do it.
- Test suites that mocked os.path.exists would experience strange failures, due
to coverage.py using their mock inadvertently. This is now fixed, closing
`issue 416`_.
- Importing a ``__init__`` module explicitly would lead to an error:
``AttributeError: 'module' object has no attribute '__path__'``, as reported
in `issue 410`_. This is now fixed.
- Code that uses ``sys.settrace(sys.gettrace())`` used to incur a more than 2x
speed penalty. Now there's no penalty at all. Fixes `issue 397`_.
- Pyexpat C code will no longer be recorded as a source file, fixing
`issue 419`_.
- The source kit now contains all of the files needed to have a complete source
tree, re-fixing `issue 137`_ and closing `issue 281`_.
.. _issue 281: https://github.com/nedbat/coveragepy/issues/281
.. _issue 397: https://github.com/nedbat/coveragepy/issues/397
.. _issue 410: https://github.com/nedbat/coveragepy/issues/410
.. _issue 415: https://github.com/nedbat/coveragepy/issues/415
.. _issue 416: https://github.com/nedbat/coveragepy/issues/416
.. _issue 418: https://github.com/nedbat/coveragepy/issues/418
.. _issue 419: https://github.com/nedbat/coveragepy/issues/419
.. _issue 423: https://github.com/nedbat/coveragepy/issues/423
.. _changes_40:
Version 4.0 โ 2015-09-20
------------------------
No changes from 4.0b3
Version 4.0b3 โ 2015-09-07
--------------------------
- Reporting on an unmeasured file would fail with a traceback. This is now
fixed, closing `issue 403`_.
- The Jenkins ShiningPanda_ plugin looks for an obsolete file name to find the
HTML reports to publish, so it was failing under coverage.py 4.0. Now we
create that file if we are running under Jenkins, to keep things working
smoothly. `issue 404`_.
- Kits used to include tests and docs, but didn't install them anywhere, or
provide all of the supporting tools to make them useful. Kits no longer
include tests and docs. If you were using them from the older packages, get
in touch and help me understand how.
.. _issue 403: https://github.com/nedbat/coveragepy/issues/403
.. _issue 404: https://github.com/nedbat/coveragepy/issues/404
Version 4.0b2 โ 2015-08-22
--------------------------
- 4.0b1 broke ``--append`` creating new data files. This is now fixed, closing
`issue 392`_.
- ``py.test --cov`` can write empty data, then touch files due to ``--source``,
which made coverage.py mistakenly force the data file to record lines instead
of arcs. This would lead to a "Can't combine line data with arc data" error
message. This is now fixed, and changed some method names in the
CoverageData interface. Fixes `issue 399`_.
- `CoverageData.read_fileobj` and `CoverageData.write_fileobj` replace the
`.read` and `.write` methods, and are now properly inverses of each other.
- When using ``report --skip-covered``, a message will now be included in the
report output indicating how many files were skipped, and if all files are
skipped, coverage.py won't accidentally scold you for having no data to
report. Thanks, Krystian Kichewko.
- A new conversion utility has been added: ``python -m coverage.pickle2json``
will convert v3.x pickle data files to v4.x JSON data files. Thanks,
Alexander Todorov. Closes `issue 395`_.
- A new version identifier is available, `coverage.version_info`, a plain tuple
of values similar to `sys.version_info`_.
.. _issue 392: https://github.com/nedbat/coveragepy/issues/392
.. _issue 395: https://github.com/nedbat/coveragepy/issues/395
.. _issue 399: https://github.com/nedbat/coveragepy/issues/399
.. _sys.version_info: https://docs.python.org/3/library/sys.html#sys.version_info
Version 4.0b1 โ 2015-08-02
--------------------------
- Coverage.py is now licensed under the Apache 2.0 license. See NOTICE.txt for
details. Closes `issue 313`_.
- The data storage has been completely revamped. The data file is now
JSON-based instead of a pickle, closing `issue 236`_. The `CoverageData`
class is now a public supported documented API to the data file.
- A new configuration option, ``[run] note``, lets you set a note that will be
stored in the `runs` section of the data file. You can use this to annotate
the data file with any information you like.
- Unrecognized configuration options will now print an error message and stop
coverage.py. This should help prevent configuration mistakes from passing
silently. Finishes `issue 386`_.
- In parallel mode, ``coverage erase`` will now delete all of the data files,
fixing `issue 262`_.
- Coverage.py now accepts a directory name for ``coverage run`` and will run a
``__main__.py`` found there, just like Python will. Fixes `issue 252`_.
Thanks, Dmitry Trofimov.
- The XML report now includes a ``missing-branches`` attribute. Thanks, Steve
Peak. This is not a part of the Cobertura DTD, so the XML report no longer
references the DTD.
- Missing branches in the HTML report now have a bit more information in the
right-hand annotations. Hopefully this will make their meaning clearer.
- All the reporting functions now behave the same if no data had been
collected, exiting with a status code of 1. Fixed ``fail_under`` to be
applied even when the report is empty. Thanks, Ionel Cristian Mฤrieศ.
- Plugins are now initialized differently. Instead of looking for a class
called ``Plugin``, coverage.py looks for a function called ``coverage_init``.
- A file-tracing plugin can now ask to have built-in Python reporting by
returning `"python"` from its `file_reporter()` method.
- Code that was executed with `exec` would be mis-attributed to the file that
called it. This is now fixed, closing `issue 380`_.
- The ability to use item access on `Coverage.config` (introduced in 4.0a2) has
been changed to a more explicit `Coverage.get_option` and
`Coverage.set_option` API.
- The ``Coverage.use_cache`` method is no longer supported.
- The private method ``Coverage._harvest_data`` is now called
``Coverage.get_data``, and returns the ``CoverageData`` containing the
collected data.
- The project is consistently referred to as "coverage.py" throughout the code
and the documentation, closing `issue 275`_.
- Combining data files with an explicit configuration file was broken in 4.0a6,
but now works again, closing `issue 385`_.
- ``coverage combine`` now accepts files as well as directories.
- The speed is back to 3.7.1 levels, after having slowed down due to plugin
support, finishing up `issue 387`_.
.. _issue 236: https://github.com/nedbat/coveragepy/issues/236
.. _issue 252: https://github.com/nedbat/coveragepy/issues/252
.. _issue 262: https://github.com/nedbat/coveragepy/issues/262
.. _issue 275: https://github.com/nedbat/coveragepy/issues/275
.. _issue 313: https://github.com/nedbat/coveragepy/issues/313
.. _issue 380: https://github.com/nedbat/coveragepy/issues/380
.. _issue 385: https://github.com/nedbat/coveragepy/issues/385
.. _issue 386: https://github.com/nedbat/coveragepy/issues/386
.. _issue 387: https://github.com/nedbat/coveragepy/issues/387
.. 40 issues closed in 4.0 below here
Version 4.0a6 โ 2015-06-21
--------------------------
- Python 3.5b2 and PyPy 2.6.0 are supported.
- The original module-level function interface to coverage.py is no longer
supported. You must now create a ``coverage.Coverage`` object, and use
methods on it.
- The ``coverage combine`` command now accepts any number of directories as
arguments, and will combine all the data files from those directories. This
means you don't have to copy the files to one directory before combining.
Thanks, Christine Lytwynec. Finishes `issue 354`_.
- Branch coverage couldn't properly handle certain extremely long files. This
is now fixed (`issue 359`_).
- Branch coverage didn't understand yield statements properly. Mickie Betz
persisted in pursuing this despite Ned's pessimism. Fixes `issue 308`_ and
`issue 324`_.
- The ``COVERAGE_DEBUG`` environment variable can be used to set the
``[run] debug`` configuration option to control what internal operations are
logged.
- HTML reports were truncated at formfeed characters. This is now fixed
(`issue 360`_). It's always fun when the problem is due to a `bug in the
Python standard library `_.
- Files with incorrect encoding declaration comments are no longer ignored by
the reporting commands, fixing `issue 351`_.
- HTML reports now include a time stamp in the footer, closing `issue 299`_.
Thanks, Conrad Ho.
- HTML reports now begrudgingly use double-quotes rather than single quotes,
because there are "software engineers" out there writing tools that read HTML
and somehow have no idea that single quotes exist. Capitulates to the absurd
`issue 361`_. Thanks, Jon Chappell.
- The ``coverage annotate`` command now handles non-ASCII characters properly,
closing `issue 363`_. Thanks, Leonardo Pistone.
- Drive letters on Windows were not normalized correctly, now they are. Thanks,
Ionel Cristian Mฤrieศ.
- Plugin support had some bugs fixed, closing `issue 374`_ and `issue 375`_.
Thanks, Stefan Behnel.
.. _issue 299: https://github.com/nedbat/coveragepy/issues/299
.. _issue 308: https://github.com/nedbat/coveragepy/issues/308
.. _issue 324: https://github.com/nedbat/coveragepy/issues/324
.. _issue 351: https://github.com/nedbat/coveragepy/issues/351
.. _issue 354: https://github.com/nedbat/coveragepy/issues/354
.. _issue 359: https://github.com/nedbat/coveragepy/issues/359
.. _issue 360: https://github.com/nedbat/coveragepy/issues/360
.. _issue 361: https://github.com/nedbat/coveragepy/issues/361
.. _issue 363: https://github.com/nedbat/coveragepy/issues/363
.. _issue 374: https://github.com/nedbat/coveragepy/issues/374
.. _issue 375: https://github.com/nedbat/coveragepy/issues/375
Version 4.0a5 โ 2015-02-16
--------------------------
- Plugin support is now implemented in the C tracer instead of the Python
tracer. This greatly improves the speed of tracing projects using plugins.
- Coverage.py now always adds the current directory to sys.path, so that
plugins can import files in the current directory (`issue 358`_).
- If the `config_file` argument to the Coverage constructor is specified as
".coveragerc", it is treated as if it were True. This means setup.cfg is
also examined, and a missing file is not considered an error (`issue 357`_).
- Wildly experimental: support for measuring processes started by the
multiprocessing module. To use, set ``--concurrency=multiprocessing``,
either on the command line or in the .coveragerc file (`issue 117`_). Thanks,
Eduardo Schettino. Currently, this does not work on Windows.
- A new warning is possible, if a desired file isn't measured because it was
imported before coverage.py was started (`issue 353`_).
- The `coverage.process_startup` function now will start coverage measurement
only once, no matter how many times it is called. This fixes problems due
to unusual virtualenv configurations (`issue 340`_).
- Added 3.5.0a1 to the list of supported CPython versions.
.. _issue 117: https://github.com/nedbat/coveragepy/issues/117
.. _issue 340: https://github.com/nedbat/coveragepy/issues/340
.. _issue 353: https://github.com/nedbat/coveragepy/issues/353
.. _issue 357: https://github.com/nedbat/coveragepy/issues/357
.. _issue 358: https://github.com/nedbat/coveragepy/issues/358
Version 4.0a4 โ 2015-01-25
--------------------------
- Plugins can now provide sys_info for debugging output.
- Started plugins documentation.
- Prepared to move the docs to readthedocs.org.
Version 4.0a3 โ 2015-01-20
--------------------------
- Reports now use file names with extensions. Previously, a report would
describe a/b/c.py as "a/b/c". Now it is shown as "a/b/c.py". This allows
for better support of non-Python files, and also fixed `issue 69`_.
- The XML report now reports each directory as a package again. This was a bad
regression, I apologize. This was reported in `issue 235`_, which is now
fixed.
- A new configuration option for the XML report: ``[xml] package_depth``
controls which directories are identified as packages in the report.
Directories deeper than this depth are not reported as packages.
The default is that all directories are reported as packages.
Thanks, Lex Berezhny.
- When looking for the source for a frame, check if the file exists. On
Windows, .pyw files are no longer recorded as .py files. Along the way, this
fixed `issue 290`_.
- Empty files are now reported as 100% covered in the XML report, not 0%
covered (`issue 345`_).
- Regexes in the configuration file are now compiled as soon as they are read,
to provide error messages earlier (`issue 349`_).
.. _issue 69: https://github.com/nedbat/coveragepy/issues/69
.. _issue 235: https://github.com/nedbat/coveragepy/issues/235
.. _issue 290: https://github.com/nedbat/coveragepy/issues/290
.. _issue 345: https://github.com/nedbat/coveragepy/issues/345
.. _issue 349: https://github.com/nedbat/coveragepy/issues/349
Version 4.0a2 โ 2015-01-14
--------------------------
- Officially support PyPy 2.4, and PyPy3 2.4. Drop support for
CPython 3.2 and older versions of PyPy. The code won't work on CPython 3.2.
It will probably still work on older versions of PyPy, but I'm not testing
against them.
- Plugins!
- The original command line switches (`-x` to run a program, etc) are no
longer supported.
- A new option: `coverage report --skip-covered` will reduce the number of
files reported by skipping files with 100% coverage. Thanks, Krystian
Kichewko. This means that empty `__init__.py` files will be skipped, since
they are 100% covered, closing `issue 315`_.
- You can now specify the ``--fail-under`` option in the ``.coveragerc`` file
as the ``[report] fail_under`` option. This closes `issue 314`_.
- The ``COVERAGE_OPTIONS`` environment variable is no longer supported. It was
a hack for ``--timid`` before configuration files were available.
- The HTML report now has filtering. Type text into the Filter box on the
index page, and only modules with that text in the name will be shown.
Thanks, Danny Allen.
- The textual report and the HTML report used to report partial branches
differently for no good reason. Now the text report's "missing branches"
column is a "partial branches" column so that both reports show the same
numbers. This closes `issue 342`_.
- If you specify a ``--rcfile`` that cannot be read, you will get an error
message. Fixes `issue 343`_.
- The ``--debug`` switch can now be used on any command.
- You can now programmatically adjust the configuration of coverage.py by
setting items on `Coverage.config` after construction.
- A module run with ``-m`` can be used as the argument to ``--source``, fixing
`issue 328`_. Thanks, Buck Evan.
- The regex for matching exclusion pragmas has been fixed to allow more kinds
of white space, fixing `issue 334`_.
- Made some PyPy-specific tweaks to improve speed under PyPy. Thanks, Alex
Gaynor.
- In some cases, with a source file missing a final newline, coverage.py would
count statements incorrectly. This is now fixed, closing `issue 293`_.
- The status.dat file that HTML reports use to avoid re-creating files that
haven't changed is now a JSON file instead of a pickle file. This obviates
`issue 287`_ and `issue 237`_.
.. _issue 237: https://github.com/nedbat/coveragepy/issues/237
.. _issue 287: https://github.com/nedbat/coveragepy/issues/287
.. _issue 293: https://github.com/nedbat/coveragepy/issues/293
.. _issue 314: https://github.com/nedbat/coveragepy/issues/314
.. _issue 315: https://github.com/nedbat/coveragepy/issues/315
.. _issue 328: https://github.com/nedbat/coveragepy/issues/328
.. _issue 334: https://github.com/nedbat/coveragepy/issues/334
.. _issue 342: https://github.com/nedbat/coveragepy/issues/342
.. _issue 343: https://github.com/nedbat/coveragepy/issues/343
Version 4.0a1 โ 2014-09-27
--------------------------
- Python versions supported are now CPython 2.6, 2.7, 3.2, 3.3, and 3.4, and
PyPy 2.2.
- Gevent, eventlet, and greenlet are now supported, closing `issue 149`_.
The ``concurrency`` setting specifies the concurrency library in use. Huge
thanks to Peter Portante for initial implementation, and to Joe Jevnik for
the final insight that completed the work.
- Options are now also read from a setup.cfg file, if any. Sections are
prefixed with "coverage:", so the ``[run]`` options will be read from the
``[coverage:run]`` section of setup.cfg. Finishes `issue 304`_.
- The ``report -m`` command can now show missing branches when reporting on
branch coverage. Thanks, Steve Leonard. Closes `issue 230`_.
- The XML report now contains a element, fixing `issue 94`_. Thanks
Stan Hu.
- The class defined in the coverage module is now called ``Coverage`` instead
of ``coverage``, though the old name still works, for backward compatibility.
- The ``fail-under`` value is now rounded the same as reported results,
preventing paradoxical results, fixing `issue 284`_.
- The XML report will now create the output directory if need be, fixing
`issue 285`_. Thanks, Chris Rose.
- HTML reports no longer raise UnicodeDecodeError if a Python file has
un-decodable characters, fixing `issue 303`_ and `issue 331`_.
- The annotate command will now annotate all files, not just ones relative to
the current directory, fixing `issue 57`_.
- The coverage module no longer causes deprecation warnings on Python 3.4 by
importing the imp module, fixing `issue 305`_.
- Encoding declarations in source files are only considered if they are truly
comments. Thanks, Anthony Sottile.
.. _issue 57: https://github.com/nedbat/coveragepy/issues/57
.. _issue 94: https://github.com/nedbat/coveragepy/issues/94
.. _issue 149: https://github.com/nedbat/coveragepy/issues/149
.. _issue 230: https://github.com/nedbat/coveragepy/issues/230
.. _issue 284: https://github.com/nedbat/coveragepy/issues/284
.. _issue 285: https://github.com/nedbat/coveragepy/issues/285
.. _issue 303: https://github.com/nedbat/coveragepy/issues/303
.. _issue 304: https://github.com/nedbat/coveragepy/issues/304
.. _issue 305: https://github.com/nedbat/coveragepy/issues/305
.. _issue 331: https://github.com/nedbat/coveragepy/issues/331
.. _changes_371:
Version 3.7.1 โ 2013-12-13
--------------------------
- Improved the speed of HTML report generation by about 20%.
- Fixed the mechanism for finding OS-installed static files for the HTML report
so that it will actually find OS-installed static files.
.. _changes_37:
Version 3.7 โ 2013-10-06
------------------------
- Added the ``--debug`` switch to ``coverage run``. It accepts a list of
options indicating the type of internal activity to log to stderr.
- Improved the branch coverage facility, fixing `issue 92`_ and `issue 175`_.
- Running code with ``coverage run -m`` now behaves more like Python does,
setting sys.path properly, which fixes `issue 207`_ and `issue 242`_.
- Coverage.py can now run .pyc files directly, closing `issue 264`_.
- Coverage.py properly supports .pyw files, fixing `issue 261`_.
- Omitting files within a tree specified with the ``source`` option would
cause them to be incorrectly marked as un-executed, as described in
`issue 218`_. This is now fixed.
- When specifying paths to alias together during data combining, you can now
specify relative paths, fixing `issue 267`_.
- Most file paths can now be specified with username expansion (``~/src``, or
``~build/src``, for example), and with environment variable expansion
(``build/$BUILDNUM/src``).
- Trying to create an XML report with no files to report on, would cause a
ZeroDivisionError, but no longer does, fixing `issue 250`_.
- When running a threaded program under the Python tracer, coverage.py no
longer issues a spurious warning about the trace function changing: "Trace
function changed, measurement is likely wrong: None." This fixes `issue
164`_.
- Static files necessary for HTML reports are found in system-installed places,
to ease OS-level packaging of coverage.py. Closes `issue 259`_.
- Source files with encoding declarations, but a blank first line, were not
decoded properly. Now they are. Thanks, Roger Hu.
- The source kit now includes the ``__main__.py`` file in the root coverage
directory, fixing `issue 255`_.
.. _issue 92: https://github.com/nedbat/coveragepy/issues/92
.. _issue 164: https://github.com/nedbat/coveragepy/issues/164
.. _issue 175: https://github.com/nedbat/coveragepy/issues/175
.. _issue 207: https://github.com/nedbat/coveragepy/issues/207
.. _issue 242: https://github.com/nedbat/coveragepy/issues/242
.. _issue 218: https://github.com/nedbat/coveragepy/issues/218
.. _issue 250: https://github.com/nedbat/coveragepy/issues/250
.. _issue 255: https://github.com/nedbat/coveragepy/issues/255
.. _issue 259: https://github.com/nedbat/coveragepy/issues/259
.. _issue 261: https://github.com/nedbat/coveragepy/issues/261
.. _issue 264: https://github.com/nedbat/coveragepy/issues/264
.. _issue 267: https://github.com/nedbat/coveragepy/issues/267
.. _changes_36:
Version 3.6 โ 2013-01-05
------------------------
- Added a page to the docs about troublesome situations, closing `issue 226`_,
and added some info to the TODO file, closing `issue 227`_.
.. _issue 226: https://github.com/nedbat/coveragepy/issues/226
.. _issue 227: https://github.com/nedbat/coveragepy/issues/227
Version 3.6b3 โ 2012-12-29
--------------------------
- Beta 2 broke the nose plugin. It's fixed again, closing `issue 224`_.
.. _issue 224: https://github.com/nedbat/coveragepy/issues/224
Version 3.6b2 โ 2012-12-23
--------------------------
- Coverage.py runs on Python 2.3 and 2.4 again. It was broken in 3.6b1.
- The C extension is optionally compiled using a different more widely-used
technique, taking another stab at fixing `issue 80`_ once and for all.
- Combining data files would create entries for phantom files if used with
``source`` and path aliases. It no longer does.
- ``debug sys`` now shows the configuration file path that was read.
- If an oddly-behaved package claims that code came from an empty-string
file name, coverage.py no longer associates it with the directory name,
fixing `issue 221`_.
.. _issue 221: https://github.com/nedbat/coveragepy/issues/221
Version 3.6b1 โ 2012-11-28
--------------------------
- Wildcards in ``include=`` and ``omit=`` arguments were not handled properly
in reporting functions, though they were when running. Now they are handled
uniformly, closing `issue 143`_ and `issue 163`_. **NOTE**: it is possible
that your configurations may now be incorrect. If you use ``include`` or
``omit`` during reporting, whether on the command line, through the API, or
in a configuration file, please check carefully that you were not relying on
the old broken behavior.
- The **report**, **html**, and **xml** commands now accept a ``--fail-under``
switch that indicates in the exit status whether the coverage percentage was
less than a particular value. Closes `issue 139`_.
- The reporting functions coverage.report(), coverage.html_report(), and
coverage.xml_report() now all return a float, the total percentage covered
measurement.
- The HTML report's title can now be set in the configuration file, with the
``--title`` switch on the command line, or via the API.
- Configuration files now support substitution of environment variables, using
syntax like ``${WORD}``. Closes `issue 97`_.
- Embarrassingly, the ``[xml] output=`` setting in the .coveragerc file simply
didn't work. Now it does.
- The XML report now consistently uses file names for the file name attribute,
rather than sometimes using module names. Fixes `issue 67`_.
Thanks, Marcus Cobden.
- Coverage percentage metrics are now computed slightly differently under
branch coverage. This means that completely un-executed files will now
correctly have 0% coverage, fixing `issue 156`_. This also means that your
total coverage numbers will generally now be lower if you are measuring
branch coverage.
- When installing, now in addition to creating a "coverage" command, two new
aliases are also installed. A "coverage2" or "coverage3" command will be
created, depending on whether you are installing in Python 2.x or 3.x.
A "coverage-X.Y" command will also be created corresponding to your specific
version of Python. Closes `issue 111`_.
- The coverage.py installer no longer tries to bootstrap setuptools or
Distribute. You must have one of them installed first, as `issue 202`_
recommended.
- The coverage.py kit now includes docs (closing `issue 137`_) and tests.
- On Windows, files are now reported in their correct case, fixing `issue 89`_
and `issue 203`_.
- If a file is missing during reporting, the path shown in the error message
is now correct, rather than an incorrect path in the current directory.
Fixes `issue 60`_.
- Running an HTML report in Python 3 in the same directory as an old Python 2
HTML report would fail with a UnicodeDecodeError. This issue (`issue 193`_)
is now fixed.
- Fixed yet another error trying to parse non-Python files as Python, this
time an IndentationError, closing `issue 82`_ for the fourth time...
- If `coverage xml` fails because there is no data to report, it used to
create a zero-length XML file. Now it doesn't, fixing `issue 210`_.
- Jython files now work with the ``--source`` option, fixing `issue 100`_.
- Running coverage.py under a debugger is unlikely to work, but it shouldn't
fail with "TypeError: 'NoneType' object is not iterable". Fixes `issue
201`_.
- On some Linux distributions, when installed with the OS package manager,
coverage.py would report its own code as part of the results. Now it won't,
fixing `issue 214`_, though this will take some time to be repackaged by the
operating systems.
- Docstrings for the legacy singleton methods are more helpful. Thanks Marius
Gedminas. Closes `issue 205`_.
- The pydoc tool can now show documentation for the class `coverage.coverage`.
Closes `issue 206`_.
- Added a page to the docs about contributing to coverage.py, closing
`issue 171`_.
- When coverage.py ended unsuccessfully, it may have reported odd errors like
``'NoneType' object has no attribute 'isabs'``. It no longer does,
so kiss `issue 153`_ goodbye.
.. _issue 60: https://github.com/nedbat/coveragepy/issues/60
.. _issue 67: https://github.com/nedbat/coveragepy/issues/67
.. _issue 89: https://github.com/nedbat/coveragepy/issues/89
.. _issue 97: https://github.com/nedbat/coveragepy/issues/97
.. _issue 100: https://github.com/nedbat/coveragepy/issues/100
.. _issue 111: https://github.com/nedbat/coveragepy/issues/111
.. _issue 137: https://github.com/nedbat/coveragepy/issues/137
.. _issue 139: https://github.com/nedbat/coveragepy/issues/139
.. _issue 143: https://github.com/nedbat/coveragepy/issues/143
.. _issue 153: https://github.com/nedbat/coveragepy/issues/153
.. _issue 156: https://github.com/nedbat/coveragepy/issues/156
.. _issue 163: https://github.com/nedbat/coveragepy/issues/163
.. _issue 171: https://github.com/nedbat/coveragepy/issues/171
.. _issue 193: https://github.com/nedbat/coveragepy/issues/193
.. _issue 201: https://github.com/nedbat/coveragepy/issues/201
.. _issue 202: https://github.com/nedbat/coveragepy/issues/202
.. _issue 203: https://github.com/nedbat/coveragepy/issues/203
.. _issue 205: https://github.com/nedbat/coveragepy/issues/205
.. _issue 206: https://github.com/nedbat/coveragepy/issues/206
.. _issue 210: https://github.com/nedbat/coveragepy/issues/210
.. _issue 214: https://github.com/nedbat/coveragepy/issues/214
.. _changes_353:
Version 3.5.3 โ 2012-09-29
--------------------------
- Line numbers in the HTML report line up better with the source lines, fixing
`issue 197`_, thanks Marius Gedminas.
- When specifying a directory as the source= option, the directory itself no
longer needs to have a ``__init__.py`` file, though its sub-directories do,
to be considered as source files.
- Files encoded as UTF-8 with a BOM are now properly handled, fixing
`issue 179`_. Thanks, Pablo Carballo.
- Fixed more cases of non-Python files being reported as Python source, and
then not being able to parse them as Python. Closes `issue 82`_ (again).
Thanks, Julian Berman.
- Fixed memory leaks under Python 3, thanks, Brett Cannon. Closes `issue 147`_.
- Optimized .pyo files may not have been handled correctly, `issue 195`_.
Thanks, Marius Gedminas.
- Certain unusually named file paths could have been mangled during reporting,
`issue 194`_. Thanks, Marius Gedminas.
- Try to do a better job of the impossible task of detecting when we can't
build the C extension, fixing `issue 183`_.
- Testing is now done with `tox`_, thanks, Marc Abramowitz.
.. _issue 147: https://github.com/nedbat/coveragepy/issues/147
.. _issue 179: https://github.com/nedbat/coveragepy/issues/179
.. _issue 183: https://github.com/nedbat/coveragepy/issues/183
.. _issue 194: https://github.com/nedbat/coveragepy/issues/194
.. _issue 195: https://github.com/nedbat/coveragepy/issues/195
.. _issue 197: https://github.com/nedbat/coveragepy/issues/197
.. _tox: https://tox.readthedocs.io/
.. _changes_352:
Version 3.5.2 โ 2012-05-04
--------------------------
No changes since 3.5.2.b1
Version 3.5.2b1 โ 2012-04-29
----------------------------
- The HTML report has slightly tweaked controls: the buttons at the top of
the page are color-coded to the source lines they affect.
- Custom CSS can be applied to the HTML report by specifying a CSS file as
the ``extra_css`` configuration value in the ``[html]`` section.
- Source files with custom encodings declared in a comment at the top are now
properly handled during reporting on Python 2. Python 3 always handled them
properly. This fixes `issue 157`_.
- Backup files left behind by editors are no longer collected by the source=
option, fixing `issue 168`_.
- If a file doesn't parse properly as Python, we don't report it as an error
if the file name seems like maybe it wasn't meant to be Python. This is a
pragmatic fix for `issue 82`_.
- The ``-m`` switch on ``coverage report``, which includes missing line numbers
in the summary report, can now be specified as ``show_missing`` in the
config file. Closes `issue 173`_.
- When running a module with ``coverage run -m ``, certain details
of the execution environment weren't the same as for
``python -m ``. This had the unfortunate side-effect of making
``coverage run -m unittest discover`` not work if you had tests in a
directory named "test". This fixes `issue 155`_ and `issue 142`_.
- Now the exit status of your product code is properly used as the process
status when running ``python -m coverage run ...``. Thanks, JT Olds.
- When installing into PyPy, we no longer attempt (and fail) to compile
the C tracer function, closing `issue 166`_.
.. _issue 142: https://github.com/nedbat/coveragepy/issues/142
.. _issue 155: https://github.com/nedbat/coveragepy/issues/155
.. _issue 157: https://github.com/nedbat/coveragepy/issues/157
.. _issue 166: https://github.com/nedbat/coveragepy/issues/166
.. _issue 168: https://github.com/nedbat/coveragepy/issues/168
.. _issue 173: https://github.com/nedbat/coveragepy/issues/173
.. _changes_351:
Version 3.5.1 โ 2011-09-23
--------------------------
- The ``[paths]`` feature unfortunately didn't work in real world situations
where you wanted to, you know, report on the combined data. Now all paths
stored in the combined file are canonicalized properly.
Version 3.5.1b1 โ 2011-08-28
----------------------------
- When combining data files from parallel runs, you can now instruct
coverage.py about which directories are equivalent on different machines. A
``[paths]`` section in the configuration file lists paths that are to be
considered equivalent. Finishes `issue 17`_.
- for-else constructs are understood better, and don't cause erroneous partial
branch warnings. Fixes `issue 122`_.
- Branch coverage for ``with`` statements is improved, fixing `issue 128`_.
- The number of partial branches reported on the HTML summary page was
different than the number reported on the individual file pages. This is
now fixed.
- An explicit include directive to measure files in the Python installation
wouldn't work because of the standard library exclusion. Now the include
directive takes precedence, and the files will be measured. Fixes
`issue 138`_.
- The HTML report now handles Unicode characters in Python source files
properly. This fixes `issue 124`_ and `issue 144`_. Thanks, Devin
Jeanpierre.
- In order to help the core developers measure the test coverage of the
standard library, Brandon Rhodes devised an aggressive hack to trick Python
into running some coverage.py code before anything else in the process.
See the coverage/fullcoverage directory if you are interested.
.. _issue 17: https://github.com/nedbat/coveragepy/issues/17
.. _issue 122: https://github.com/nedbat/coveragepy/issues/122
.. _issue 124: https://github.com/nedbat/coveragepy/issues/124
.. _issue 128: https://github.com/nedbat/coveragepy/issues/128
.. _issue 138: https://github.com/nedbat/coveragepy/issues/138
.. _issue 144: https://github.com/nedbat/coveragepy/issues/144
.. _changes_35:
Version 3.5 โ 2011-06-29
------------------------
- The HTML report hotkeys now behave slightly differently when the current
chunk isn't visible at all: a chunk on the screen will be selected,
instead of the old behavior of jumping to the literal next chunk.
The hotkeys now work in Google Chrome. Thanks, Guido van Rossum.
Version 3.5b1 โ 2011-06-05
--------------------------
- The HTML report now has hotkeys. Try ``n``, ``s``, ``m``, ``x``, ``b``,
``p``, and ``c`` on the overview page to change the column sorting.
On a file page, ``r``, ``m``, ``x``, and ``p`` toggle the run, missing,
excluded, and partial line markings. You can navigate the highlighted
sections of code by using the ``j`` and ``k`` keys for next and previous.
The ``1`` (one) key jumps to the first highlighted section in the file,
and ``0`` (zero) scrolls to the top of the file.
- The ``--omit`` and ``--include`` switches now interpret their values more
usefully. If the value starts with a wildcard character, it is used as-is.
If it does not, it is interpreted relative to the current directory.
Closes `issue 121`_.
- Partial branch warnings can now be pragma'd away. The configuration option
``partial_branches`` is a list of regular expressions. Lines matching any of
those expressions will never be marked as a partial branch. In addition,
there's a built-in list of regular expressions marking statements which
should never be marked as partial. This list includes ``while True:``,
``while 1:``, ``if 1:``, and ``if 0:``.
- The ``coverage()`` constructor accepts single strings for the ``omit=`` and
``include=`` arguments, adapting to a common error in programmatic use.
- Modules can now be run directly using ``coverage run -m modulename``, to
mirror Python's ``-m`` flag. Closes `issue 95`_, thanks, Brandon Rhodes.
- ``coverage run`` didn't emulate Python accurately in one small detail: the
current directory inserted into ``sys.path`` was relative rather than
absolute. This is now fixed.
- HTML reporting is now incremental: a record is kept of the data that
produced the HTML reports, and only files whose data has changed will
be generated. This should make most HTML reporting faster.
- Pathological code execution could disable the trace function behind our
backs, leading to incorrect code measurement. Now if this happens,
coverage.py will issue a warning, at least alerting you to the problem.
Closes `issue 93`_. Thanks to Marius Gedminas for the idea.
- The C-based trace function now behaves properly when saved and restored
with ``sys.gettrace()`` and ``sys.settrace()``. This fixes `issue 125`_
and `issue 123`_. Thanks, Devin Jeanpierre.
- Source files are now opened with Python 3.2's ``tokenize.open()`` where
possible, to get the best handling of Python source files with encodings.
Closes `issue 107`_, thanks, Brett Cannon.
- Syntax errors in supposed Python files can now be ignored during reporting
with the ``-i`` switch just like other source errors. Closes `issue 115`_.
- Installation from source now succeeds on machines without a C compiler,
closing `issue 80`_.
- Coverage.py can now be run directly from a working tree by specifying
the directory name to python: ``python coverage_py_working_dir run ...``.
Thanks, Brett Cannon.
- A little bit of Jython support: `coverage run` can now measure Jython
execution by adapting when $py.class files are traced. Thanks, Adi Roiban.
Jython still doesn't provide the Python libraries needed to make
coverage reporting work, unfortunately.
- Internally, files are now closed explicitly, fixing `issue 104`_. Thanks,
Brett Cannon.
.. _issue 80: https://github.com/nedbat/coveragepy/issues/80
.. _issue 93: https://github.com/nedbat/coveragepy/issues/93
.. _issue 95: https://github.com/nedbat/coveragepy/issues/95
.. _issue 104: https://github.com/nedbat/coveragepy/issues/104
.. _issue 107: https://github.com/nedbat/coveragepy/issues/107
.. _issue 115: https://github.com/nedbat/coveragepy/issues/115
.. _issue 121: https://github.com/nedbat/coveragepy/issues/121
.. _issue 123: https://github.com/nedbat/coveragepy/issues/123
.. _issue 125: https://github.com/nedbat/coveragepy/issues/125
.. _changes_34:
Version 3.4 โ 2010-09-19
------------------------
- The XML report is now sorted by package name, fixing `issue 88`_.
- Programs that exited with ``sys.exit()`` with no argument weren't handled
properly, producing a coverage.py stack trace. That is now fixed.
.. _issue 88: https://github.com/nedbat/coveragepy/issues/88
Version 3.4b2 โ 2010-09-06
--------------------------
- Completely un-executed files can now be included in coverage results,
reported as 0% covered. This only happens if the --source option is
specified, since coverage.py needs guidance about where to look for source
files.
- The XML report output now properly includes a percentage for branch coverage,
fixing `issue 65`_ and `issue 81`_.
- Coverage percentages are now displayed uniformly across reporting methods.
Previously, different reports could round percentages differently. Also,
percentages are only reported as 0% or 100% if they are truly 0 or 100, and
are rounded otherwise. Fixes `issue 41`_ and `issue 70`_.
- The precision of reported coverage percentages can be set with the
``[report] precision`` config file setting. Completes `issue 16`_.
- Threads derived from ``threading.Thread`` with an overridden `run` method
would report no coverage for the `run` method. This is now fixed, closing
`issue 85`_.
.. _issue 16: https://github.com/nedbat/coveragepy/issues/16
.. _issue 41: https://github.com/nedbat/coveragepy/issues/41
.. _issue 65: https://github.com/nedbat/coveragepy/issues/65
.. _issue 70: https://github.com/nedbat/coveragepy/issues/70
.. _issue 81: https://github.com/nedbat/coveragepy/issues/81
.. _issue 85: https://github.com/nedbat/coveragepy/issues/85
Version 3.4b1 โ 2010-08-21
--------------------------
- BACKWARD INCOMPATIBILITY: the ``--omit`` and ``--include`` switches now take
file patterns rather than file prefixes, closing `issue 34`_ and `issue 36`_.
- BACKWARD INCOMPATIBILITY: the `omit_prefixes` argument is gone throughout
coverage.py, replaced with `omit`, a list of file name patterns suitable for
`fnmatch`. A parallel argument `include` controls what files are included.
- The run command now has a ``--source`` switch, a list of directories or
module names. If provided, coverage.py will only measure execution in those
source files.
- Various warnings are printed to stderr for problems encountered during data
measurement: if a ``--source`` module has no Python source to measure, or is
never encountered at all, or if no data is collected.
- The reporting commands (report, annotate, html, and xml) now have an
``--include`` switch to restrict reporting to modules matching those file
patterns, similar to the existing ``--omit`` switch. Thanks, Zooko.
- The run command now supports ``--include`` and ``--omit`` to control what
modules it measures. This can speed execution and reduce the amount of data
during reporting. Thanks Zooko.
- Since coverage.py 3.1, using the Python trace function has been slower than
it needs to be. A cache of tracing decisions was broken, but has now been
fixed.
- Python 2.7 and 3.2 have introduced new opcodes that are now supported.
- Python files with no statements, for example, empty ``__init__.py`` files,
are now reported as having zero statements instead of one. Fixes `issue 1`_.
- Reports now have a column of missed line counts rather than executed line
counts, since developers should focus on reducing the missed lines to zero,
rather than increasing the executed lines to varying targets. Once
suggested, this seemed blindingly obvious.
- Line numbers in HTML source pages are clickable, linking directly to that
line, which is highlighted on arrival. Added a link back to the index page
at the bottom of each HTML page.
- Programs that call ``os.fork`` will properly collect data from both the child
and parent processes. Use ``coverage run -p`` to get two data files that can
be combined with ``coverage combine``. Fixes `issue 56`_.
- Coverage.py is now runnable as a module: ``python -m coverage``. Thanks,
Brett Cannon.
- When measuring code running in a virtualenv, most of the system library was
being measured when it shouldn't have been. This is now fixed.
- Doctest text files are no longer recorded in the coverage data, since they
can't be reported anyway. Fixes `issue 52`_ and `issue 61`_.
- Jinja HTML templates compile into Python code using the HTML file name,
which confused coverage.py. Now these files are no longer traced, fixing
`issue 82`_.
- Source files can have more than one dot in them (foo.test.py), and will be
treated properly while reporting. Fixes `issue 46`_.
- Source files with DOS line endings are now properly tokenized for syntax
coloring on non-DOS machines. Fixes `issue 53`_.
- Unusual code structure that confused exits from methods with exits from
classes is now properly analyzed. See `issue 62`_.
- Asking for an HTML report with no files now shows a nice error message rather
than a cryptic failure ('int' object is unsubscriptable). Fixes `issue 59`_.
.. _issue 1: https://github.com/nedbat/coveragepy/issues/1
.. _issue 34: https://github.com/nedbat/coveragepy/issues/34
.. _issue 36: https://github.com/nedbat/coveragepy/issues/36
.. _issue 46: https://github.com/nedbat/coveragepy/issues/46
.. _issue 53: https://github.com/nedbat/coveragepy/issues/53
.. _issue 52: https://github.com/nedbat/coveragepy/issues/52
.. _issue 56: https://github.com/nedbat/coveragepy/issues/56
.. _issue 61: https://github.com/nedbat/coveragepy/issues/61
.. _issue 62: https://github.com/nedbat/coveragepy/issues/62
.. _issue 59: https://github.com/nedbat/coveragepy/issues/59
.. _issue 82: https://github.com/nedbat/coveragepy/issues/82
.. _changes_331:
Version 3.3.1 โ 2010-03-06
--------------------------
- Using `parallel=True` in .coveragerc file prevented reporting, but now does
not, fixing `issue 49`_.
- When running your code with "coverage run", if you call `sys.exit()`,
coverage.py will exit with that status code, fixing `issue 50`_.
.. _issue 49: https://github.com/nedbat/coveragepy/issues/49
.. _issue 50: https://github.com/nedbat/coveragepy/issues/50
.. _changes_33:
Version 3.3 โ 2010-02-24
------------------------
- Settings are now read from a .coveragerc file. A specific file can be
specified on the command line with --rcfile=FILE. The name of the file can
be programmatically set with the `config_file` argument to the coverage()
constructor, or reading a config file can be disabled with
`config_file=False`.
- Fixed a problem with nested loops having their branch possibilities
mis-characterized: `issue 39`_.
- Added coverage.process_start to enable coverage measurement when Python
starts.
- Parallel data file names now have a random number appended to them in
addition to the machine name and process id.
- Parallel data files combined with "coverage combine" are deleted after
they're combined, to clean up unneeded files. Fixes `issue 40`_.
- Exceptions thrown from product code run with "coverage run" are now displayed
without internal coverage.py frames, so the output is the same as when the
code is run without coverage.py.
- The `data_suffix` argument to the coverage constructor is now appended with
an added dot rather than simply appended, so that .coveragerc files will not
be confused for data files.
- Python source files that don't end with a newline can now be executed, fixing
`issue 47`_.
- Added an AUTHORS.txt file.
.. _issue 39: https://github.com/nedbat/coveragepy/issues/39
.. _issue 40: https://github.com/nedbat/coveragepy/issues/40
.. _issue 47: https://github.com/nedbat/coveragepy/issues/47
.. _changes_32:
Version 3.2 โ 2009-12-05
------------------------
- Added a ``--version`` option on the command line.
Version 3.2b4 โ 2009-12-01
--------------------------
- Branch coverage improvements:
- The XML report now includes branch information.
- Click-to-sort HTML report columns are now persisted in a cookie. Viewing
a report will sort it first the way you last had a coverage report sorted.
Thanks, `Chris Adams`_.
- On Python 3.x, setuptools has been replaced by `Distribute`_.
.. _Distribute: https://pypi.org/project/distribute/
Version 3.2b3 โ 2009-11-23
--------------------------
- Fixed a memory leak in the C tracer that was introduced in 3.2b1.
- Branch coverage improvements:
- Branches to excluded code are ignored.
- The table of contents in the HTML report is now sortable: click the headers
on any column. Thanks, `Chris Adams`_.
.. _Chris Adams: http://chris.improbable.org
Version 3.2b2 โ 2009-11-19
--------------------------
- Branch coverage improvements:
- Classes are no longer incorrectly marked as branches: `issue 32`_.
- "except" clauses with types are no longer incorrectly marked as branches:
`issue 35`_.
- Fixed some problems syntax coloring sources with line continuations and
source with tabs: `issue 30`_ and `issue 31`_.
- The --omit option now works much better than before, fixing `issue 14`_ and
`issue 33`_. Thanks, Danek Duvall.
.. _issue 14: https://github.com/nedbat/coveragepy/issues/14
.. _issue 30: https://github.com/nedbat/coveragepy/issues/30
.. _issue 31: https://github.com/nedbat/coveragepy/issues/31
.. _issue 32: https://github.com/nedbat/coveragepy/issues/32
.. _issue 33: https://github.com/nedbat/coveragepy/issues/33
.. _issue 35: https://github.com/nedbat/coveragepy/issues/35
Version 3.2b1 โ 2009-11-10
--------------------------
- Branch coverage!
- XML reporting has file paths that let Cobertura find the source code.
- The tracer code has changed, it's a few percent faster.
- Some exceptions reported by the command line interface have been cleaned up
so that tracebacks inside coverage.py aren't shown. Fixes `issue 23`_.
.. _issue 23: https://github.com/nedbat/coveragepy/issues/23
.. _changes_31:
Version 3.1 โ 2009-10-04
------------------------
- Source code can now be read from eggs. Thanks, Ross Lawley. Fixes
`issue 25`_.
.. _issue 25: https://github.com/nedbat/coveragepy/issues/25
Version 3.1b1 โ 2009-09-27
--------------------------
- Python 3.1 is now supported.
- Coverage.py has a new command line syntax with sub-commands. This expands
the possibilities for adding features and options in the future. The old
syntax is still supported. Try "coverage help" to see the new commands.
Thanks to Ben Finney for early help.
- Added an experimental "coverage xml" command for producing coverage reports
in a Cobertura-compatible XML format. Thanks, Bill Hart.
- Added the --timid option to enable a simpler slower trace function that works
for DecoratorTools projects, including TurboGears. Fixed `issue 12`_ and
`issue 13`_.
- HTML reports show modules from other directories. Fixed `issue 11`_.
- HTML reports now display syntax-colored Python source.
- Programs that change directory will still write .coverage files in the
directory where execution started. Fixed `issue 24`_.
- Added a "coverage debug" command for getting diagnostic information about the
coverage.py installation.
.. _issue 11: https://github.com/nedbat/coveragepy/issues/11
.. _issue 12: https://github.com/nedbat/coveragepy/issues/12
.. _issue 13: https://github.com/nedbat/coveragepy/issues/13
.. _issue 24: https://github.com/nedbat/coveragepy/issues/24
.. _changes_301:
Version 3.0.1 โ 2009-07-07
--------------------------
- Removed the recursion limit in the tracer function. Previously, code that
ran more than 500 frames deep would crash. Fixed `issue 9`_.
- Fixed a bizarre problem involving pyexpat, whereby lines following XML parser
invocations could be overlooked. Fixed `issue 10`_.
- On Python 2.3, coverage.py could mis-measure code with exceptions being
raised. This is now fixed.
- The coverage.py code itself will now not be measured by coverage.py, and no
coverage.py modules will be mentioned in the nose --with-cover plug-in.
Fixed `issue 8`_.
- When running source files, coverage.py now opens them in universal newline
mode just like Python does. This lets it run Windows files on Mac, for
example.
.. _issue 9: https://github.com/nedbat/coveragepy/issues/9
.. _issue 10: https://github.com/nedbat/coveragepy/issues/10
.. _issue 8: https://github.com/nedbat/coveragepy/issues/8
.. _changes_30:
Version 3.0 โ 2009-06-13
------------------------
- Fixed the way the Python library was ignored. Too much code was being
excluded the old way.
- Tabs are now properly converted in HTML reports. Previously indentation was
lost. Fixed `issue 6`_.
- Nested modules now get a proper flat_rootname. Thanks, Christian Heimes.
.. _issue 6: https://github.com/nedbat/coveragepy/issues/6
Version 3.0b3 โ 2009-05-16
--------------------------
- Added parameters to coverage.__init__ for options that had been set on the
coverage object itself.
- Added clear_exclude() and get_exclude_list() methods for programmatic
manipulation of the exclude regexes.
- Added coverage.load() to read previously-saved data from the data file.
- Improved the finding of code files. For example, .pyc files that have been
installed after compiling are now located correctly. Thanks, Detlev
Offenbach.
- When using the object API (that is, constructing a coverage() object), data
is no longer saved automatically on process exit. You can re-enable it with
the auto_data=True parameter on the coverage() constructor. The module-level
interface still uses automatic saving.
Version 3.0b2 โ 2009-04-30
--------------------------
HTML reporting, and continued refactoring.
- HTML reports and annotation of source files: use the new -b (browser) switch.
Thanks to George Song for code, inspiration and guidance.
- Code in the Python standard library is not measured by default. If you need
to measure standard library code, use the -L command-line switch during
execution, or the cover_pylib=True argument to the coverage() constructor.
- Source annotation into a directory (-a -d) behaves differently. The
annotated files are named with their hierarchy flattened so that same-named
files from different directories no longer collide. Also, only files in the
current tree are included.
- coverage.annotate_file is no longer available.
- Programs executed with -x now behave more as they should, for example,
__file__ has the correct value.
- .coverage data files have a new pickle-based format designed for better
extensibility.
- Removed the undocumented cache_file argument to coverage.usecache().
Version 3.0b1 โ 2009-03-07
--------------------------
Major overhaul.
- Coverage.py is now a package rather than a module. Functionality has been
split into classes.
- The trace function is implemented in C for speed. Coverage.py runs are now
much faster. Thanks to David Christian for productive micro-sprints and
other encouragement.
- Executable lines are identified by reading the line number tables in the
compiled code, removing a great deal of complicated analysis code.
- Precisely which lines are considered executable has changed in some cases.
Therefore, your coverage stats may also change slightly.
- The singleton coverage object is only created if the module-level functions
are used. This maintains the old interface while allowing better
programmatic use of coverage.py.
- The minimum supported Python version is 2.3.
Version 2.85 โ 2008-09-14
-------------------------
- Add support for finding source files in eggs. Don't check for
morf's being instances of ModuleType, instead use duck typing so that
pseudo-modules can participate. Thanks, Imri Goldberg.
- Use os.realpath as part of the fixing of file names so that symlinks won't
confuse things. Thanks, Patrick Mezard.
Version 2.80 โ 2008-05-25
-------------------------
- Open files in rU mode to avoid line ending craziness. Thanks, Edward Loper.
Version 2.78 โ 2007-09-30
-------------------------
- Don't try to predict whether a file is Python source based on the extension.
Extension-less files are often Pythons scripts. Instead, simply parse the
file and catch the syntax errors. Hat tip to Ben Finney.
Version 2.77 โ 2007-07-29
-------------------------
- Better packaging.
Version 2.76 โ 2007-07-23
-------------------------
- Now Python 2.5 is *really* fully supported: the body of the new with
statement is counted as executable.
Version 2.75 โ 2007-07-22
-------------------------
- Python 2.5 now fully supported. The method of dealing with multi-line
statements is now less sensitive to the exact line that Python reports during
execution. Pass statements are handled specially so that their disappearance
during execution won't throw off the measurement.
Version 2.7 โ 2007-07-21
------------------------
- "#pragma: nocover" is excluded by default.
- Properly ignore docstrings and other constant expressions that appear in the
middle of a function, a problem reported by Tim Leslie.
- coverage.erase() shouldn't clobber the exclude regex. Change how parallel
mode is invoked, and fix erase() so that it erases the cache when called
programmatically.
- In reports, ignore code executed from strings, since we can't do anything
useful with it anyway.
- Better file handling on Linux, thanks Guillaume Chazarain.
- Better shell support on Windows, thanks Noel O'Boyle.
- Python 2.2 support maintained, thanks Catherine Proulx.
- Minor changes to avoid lint warnings.
Version 2.6 โ 2006-08-23
------------------------
- Applied Joseph Tate's patch for function decorators.
- Applied Sigve Tjora and Mark van der Wal's fixes for argument handling.
- Applied Geoff Bache's parallel mode patch.
- Refactorings to improve testability. Fixes to command-line logic for parallel
mode and collect.
Version 2.5 โ 2005-12-04
------------------------
- Call threading.settrace so that all threads are measured. Thanks Martin
Fuzzey.
- Add a file argument to report so that reports can be captured to a different
destination.
- Coverage.py can now measure itself.
- Adapted Greg Rogers' patch for using relative file names, and sorting and
omitting files to report on.
Version 2.2 โ 2004-12-31
------------------------
- Allow for keyword arguments in the module global functions. Thanks, Allen.
Version 2.1 โ 2004-12-14
------------------------
- Return 'analysis' to its original behavior and add 'analysis2'. Add a global
for 'annotate', and factor it, adding 'annotate_file'.
Version 2.0 โ 2004-12-12
------------------------
Significant code changes.
- Finding executable statements has been rewritten so that docstrings and
other quirks of Python execution aren't mistakenly identified as missing
lines.
- Lines can be excluded from consideration, even entire suites of lines.
- The file system cache of covered lines can be disabled programmatically.
- Modernized the code.
Earlier History
---------------
2001-12-04 GDR Created.
2001-12-06 GDR Added command-line interface and source code annotation.
2001-12-09 GDR Moved design and interface to separate documents.
2001-12-10 GDR Open cache file as binary on Windows. Allow simultaneous -e and
-x, or -a and -r.
2001-12-12 GDR Added command-line help. Cache analysis so that it only needs to
be done once when you specify -a and -r.
2001-12-13 GDR Improved speed while recording. Portable between Python 1.5.2
and 2.1.1.
2002-01-03 GDR Module-level functions work correctly.
2002-01-07 GDR Update sys.path when running a file with the -x option, so that
it matches the value the program would get if it were run on its own.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/cog_helpers.py 0000644 0001751 0001751 00000005650 15073731535 016471 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""
Functions for use with cog in the documentation.
"""
# For help text in doc/cmd.rst:
# optparse wraps help to the COLUMNS value. Set it here to be sure it's
# consistent regardless of the environment. Has to be set before we
# import cmdline.py, which creates the optparse objects.
# pylint: disable=wrong-import-position
import os
os.environ["COLUMNS"] = "80"
import contextlib
import io
import re
import textwrap
import cog # pylint: disable=import-error
from coverage.cmdline import CoverageScript
from coverage.config import read_coverage_config
def show_help(cmd):
"""
Insert the help output from a command.
"""
with contextlib.redirect_stdout(io.StringIO()) as stdout:
CoverageScript().command_line([cmd, "--help"])
help_text = stdout.getvalue()
help_text = help_text.replace("__main__.py", "coverage")
help_text = re.sub(r"(?m)^Full doc.*$", "", help_text)
help_text = help_text.rstrip()
print(".. code::\n")
print(f" $ coverage {cmd} --help")
print(textwrap.indent(help_text, " "))
def _read_config(text, fname):
"""
Prep and read configuration text.
Returns the prepared text, and a dict of the settings.
"""
# Text will be triple-quoted with an initial ignored newline.
assert text[0] == "\n"
text = textwrap.dedent(text[1:])
os.makedirs("tmp", exist_ok=True)
with open(f"tmp/{fname}", "w", encoding="utf-8") as f:
f.write(text)
config = read_coverage_config(f"tmp/{fname}", warn=cog.error)
values = {}
for name, val in vars(config).items():
if name.startswith("_"):
continue
if "config_file" in name:
continue
values[name] = val
return text, values
def show_configs(ini, toml):
"""
Show configuration text in a tabbed box.
`ini` is the ini-file syntax, `toml` is the equivalent TOML syntax.
The equivalence is checked for accuracy, and the process fails if there's
a mismatch.
A three-tabbed box will be produced.
"""
ini, ini_vals = _read_config(ini, "covrc")
toml, toml_vals = _read_config(toml, "covrc.toml")
for key, val in ini_vals.items():
if val != toml_vals[key]:
cog.error(
f"Mismatch between configuration tabs in docs for {key = }:\n"
+ f" ini: {val!r}\n"
+ f" toml: {toml_vals[key]!r}"
)
ini2 = re.sub(r"(?m)^\[", "[coverage:", ini)
print()
print(".. tabs::\n")
for name, syntax, text in [
(".coveragerc", "ini", ini),
("pyproject.toml", "toml", toml),
("setup.cfg or tox.ini", "ini", ini2),
]:
print(f" .. code-tab:: {syntax}")
print(f" :caption: {name}")
print()
print(textwrap.indent(text, " " * 8))
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1760539503.9501894
coverage-7.11.0/doc/commands/ 0000755 0001751 0001751 00000000000 15073731560 015416 5 ustar 00runner runner ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_annotate.rst 0000644 0001751 0001751 00000005501 15073731535 020607 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_annotate:
Text annotation: ``coverage annotate``
--------------------------------------
.. note::
The **annotate** command has been obsoleted by more modern reporting tools,
including the **html** command. The command is still supported, but won't
be getting new features.
The **annotate** command produces a text annotation of your source code. With
a ``-d`` argument specifying an output directory, each Python file becomes a
text file in that directory. Without ``-d``, the files are written into the
same directories as the original Python files.
Coverage status for each line of source is indicated with a character prefix::
> executed
! missing (not executed)
- excluded
For example::
# A simple function, never called with x==1
> def h(x):
"""Silly function."""
- if 0: # pragma: no cover
- pass
> if x == 1:
! a = 1
> else:
> a = 2
.. [[[cog show_help("annotate") ]]]
.. code::
$ coverage annotate --help
Usage: coverage annotate [options] [modules]
Make annotated copies of the given files, marking statements that are executed
with > and statements that are missed with !.
Options:
-d DIR, --directory=DIR
Write the output files to DIR.
--data-file=INFILE Read coverage data for report generation from this
file. Defaults to '.coverage'. [env: COVERAGE_FILE]
-i, --ignore-errors Ignore errors while reading source files.
--include=PAT1,PAT2,...
Include only files whose paths match one of these
patterns. Accepts shell-style wildcards, which must be
quoted.
--omit=PAT1,PAT2,... Omit files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
--debug=OPTS Debug options, separated by commas. [env:
COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are
tried. [env: COVERAGE_RCFILE]
.. [[[end]]] (sum: /X2PvS3W4k)
Other common reporting options are described above in :ref:`cmd_reporting`.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_combine.rst 0000644 0001751 0001751 00000011717 15073731535 020420 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_combine:
Combining data files: ``coverage combine``
------------------------------------------
Often test suites are run under different conditions, for example, with
different versions of Python, or dependencies, or on different operating
systems. In these cases, you can collect coverage data for each test run, and
then combine all the separate data files into one combined file for reporting.
The **combine** command reads a number of separate data files, matches the data
by source file name, and writes a combined data file with all of the data.
Coverage normally writes data to a filed named ".coverage". The ``run
--parallel-mode`` switch (or ``[run] parallel=True`` configuration option)
tells coverage to expand the file name to include machine name, process id, and
a random number so that every data file is distinct::
.coverage.Neds-MacBook-Pro.local.88335.316857
.coverage.Geometer.8044.799674
You can also define a new data file name with the ``[run] data_file`` option.
Once you have created a number of these files, you can copy them all to a
single directory, and use the **combine** command to combine them into one
.coverage data file::
$ coverage combine
You can also name directories or files to be combined on the command line::
$ coverage combine data1.dat windows_data_files/
Coverage.py will collect the data from those places and combine them. The
current directory isn't searched if you use command-line arguments. If you
also want data from the current directory, name it explicitly on the command
line.
When coverage.py combines data files, it looks for files named the same as the
data file (defaulting to ".coverage"), with a dotted suffix. Here are some
examples of data files that can be combined::
.coverage.machine1
.coverage.20120807T212300
.coverage.last_good_run.ok
An existing combined data file is ignored and re-written. If you want to use
**combine** to accumulate results into the .coverage data file over a number of
runs, use the ``--append`` switch on the **combine** command. This behavior
was the default before version 4.2.
If any of the data files can't be read, coverage.py will print a warning
indicating the file and the problem.
The original input data files are deleted once they've been combined. If you
want to keep those files, use the ``--keep`` command-line option.
.. [[[cog show_help("combine") ]]]
.. code::
$ coverage combine --help
Usage: coverage combine [options] ...
Combine data from multiple coverage files. The combined results are written to
a single file representing the union of the data. The positional arguments are
data files or directories containing data files. If no paths are provided,
data files in the default data file's directory are combined.
Options:
-a, --append Append data to the data file. Otherwise it starts
clean each time.
--data-file=DATAFILE Base name of the data files to operate on. Defaults to
'.coverage'. [env: COVERAGE_FILE]
--keep Keep original coverage files, otherwise they are
deleted.
-q, --quiet Don't print messages about what is happening.
--debug=OPTS Debug options, separated by commas. [env:
COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are
tried. [env: COVERAGE_RCFILE]
.. [[[end]]] (sum: ARyg8KB1fE)
.. _cmd_combine_remapping:
Re-mapping paths
................
To combine data for a source file, coverage has to find its data in each of the
data files. Different test runs may run the same source file from different
locations. For example, different operating systems will use different paths
for the same file, or perhaps each Python version is run from a different
subdirectory. Coverage needs to know that different file paths are actually
the same source file for reporting purposes.
You can tell coverage.py how different source locations relate with a
``[paths]`` section in your configuration file (see :ref:`config_paths`).
It might be more convenient to use the ``[run] relative_files``
setting to store relative file paths (see :ref:`relative_files
`).
If data isn't combining properly, you can see details about the inner workings
with ``--debug=pathmap``.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_debug.rst 0000644 0001751 0001751 00000011017 15073731535 020063 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_debug:
Diagnostics: ``coverage debug``
-------------------------------
The **debug** command shows internal information to help diagnose problems.
If you are reporting a bug about coverage.py, including the output of this
command can often help::
$ coverage debug sys > please_attach_to_bug_report.txt
A few types of information are available:
* ``config``: show coverage's configuration
* ``sys``: show system configuration
* ``data``: show a summary of the collected coverage data
* ``premain``: show the call stack invoking coverage
* ``pybehave``: show internal flags describing Python behavior
.. [[[cog show_help("debug") ]]]
.. code::
$ coverage debug --help
Usage: coverage debug
Display information about the internals of coverage.py, for diagnosing
problems. Topics are: 'data' to show a summary of the collected data; 'sys' to
show installation information; 'config' to show the configuration; 'premain'
to show what is calling coverage; 'pybehave' to show internal flags describing
Python behavior.
Options:
--debug=OPTS Debug options, separated by commas. [env: COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
[env: COVERAGE_RCFILE]
.. [[[end]]] (sum: ybjftkTaNE)
.. _cmd_run_debug:
``--debug`` option
..................
The ``--debug`` option is available on all commands. It instructs
coverage.py to log internal details of its operation to help with diagnosing
problems. It takes a comma-separated list of options, each indicating a facet
of activity to log:
* ``callers``: annotate each debug message with a stack trace of the callers
to that point.
* ``config``: before starting, dump all the :ref:`configuration `
values.
* ``dataio``: log when reading or writing any data file.
* ``dataop``: log a summary of data being added to CoverageData objects.
* ``dataop2``: when used with ``debug=dataop``, log the actual data being added
to CoverageData objects.
* ``lock``: log operations acquiring locks in the data layer.
* ``multiproc``: log the start and stop of multiprocessing processes.
* ``patch``: log when patches are applied and when they are executed. See
:ref:`config_run_patch`.
* ``pathmap``: log the remapping of paths that happens during ``coverage
combine``. See :ref:`config_paths`.
* ``pid``: annotate all warnings and debug output with the process and thread
ids.
* ``plugin``: print information about plugin operations.
* ``process``: show process creation information, and changes in the current
directory. This also writes a time stamp and command arguments into the data
file.
* ``pybehave``: show the values of `internal flags `_ describing the
behavior of the current version of Python.
* ``pytest``: indicate the name of the current pytest test when it changes.
* ``self``: annotate each debug message with the object printing the message.
* ``sql``: log the SQL statements used for recording data.
* ``sqldata``: when used with ``debug=sql``, also log the full data being used
in SQL statements.
* ``sys``: before starting, dump all the system and environment information,
as with :ref:`coverage debug sys `.
* ``trace``: print every decision about whether to trace a file or not. For
files not being traced, the reason is also given.
.. _env.py: https://github.com/nedbat/coveragepy/blob/master/coverage/env.py
Debug options can also be set with the ``COVERAGE_DEBUG`` environment variable,
a comma-separated list of these options, or in the :ref:`config_run_debug`
section of the .coveragerc file.
The debug output goes to stderr, unless the :ref:`config_run_debug_file`
setting or the ``COVERAGE_DEBUG_FILE`` environment variable names a different
file, which will be appended to. This can be useful because many test runners
capture output, which could hide important details. ``COVERAGE_DEBUG_FILE``
accepts the special names ``stdout`` and ``stderr`` to write to those
destinations.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_erase.rst 0000644 0001751 0001751 00000002610 15073731535 020073 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_erase:
Erase data: ``coverage erase``
------------------------------
To erase the collected data, use the **erase** command:
.. [[[cog show_help("erase") ]]]
.. code::
$ coverage erase --help
Usage: coverage erase [options]
Erase previously collected coverage data.
Options:
--data-file=DATAFILE Base name of the data files to operate on. Defaults to
'.coverage'. [env: COVERAGE_FILE]
--debug=OPTS Debug options, separated by commas. [env:
COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are
tried. [env: COVERAGE_RCFILE]
.. [[[end]]] (sum: z+rvZs6NUV)
If your configuration file indicates parallel data collection, **erase** will
remove all of the data files.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_html.rst 0000644 0001751 0001751 00000011777 15073731535 017756 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_html:
HTML reporting: ``coverage html``
---------------------------------
Coverage.py can annotate your source code to show which lines were executed
and which were not. The **html** command creates an HTML report similar to the
**report** summary, but as an HTML file. Each module name links to the source
file decorated to show the status of each line.
Here's a `sample report`__.
__ https://nedbatchelder.com/files/sample_coverage_html/index.html
Lines are highlighted: green for executed, red for missing, and gray for
excluded. If you've used branch coverage, partial branches are yellow. The
colored counts at the top of the file are buttons to turn on and off the
highlighting.
A number of keyboard shortcuts are available for navigating the report.
Click the keyboard icon in the upper right to see the complete list.
.. [[[cog show_help("html") ]]]
.. code::
$ coverage html --help
Usage: coverage html [options] [modules]
Create an HTML report of the coverage of the files. Each file gets its own
page, with the source decorated to show executed, excluded, and missed lines.
Options:
--contexts=REGEX1,REGEX2,...
Only display data from lines covered in the given
contexts. Accepts Python regexes, which must be
quoted.
-d DIR, --directory=DIR
Write the output files to DIR.
--data-file=INFILE Read coverage data for report generation from this
file. Defaults to '.coverage'. [env: COVERAGE_FILE]
--fail-under=MIN Exit with a status of 2 if the total coverage is less
than MIN.
-i, --ignore-errors Ignore errors while reading source files.
--include=PAT1,PAT2,...
Include only files whose paths match one of these
patterns. Accepts shell-style wildcards, which must be
quoted.
--omit=PAT1,PAT2,... Omit files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
--precision=N Number of digits after the decimal point to display
for reported coverage percentages.
-q, --quiet Don't print messages about what is happening.
--show-contexts Show contexts for covered lines.
--skip-covered Skip files with 100% coverage.
--no-skip-covered Disable --skip-covered.
--skip-empty Skip files with no code.
--title=TITLE A text string to use as the title on the HTML.
--debug=OPTS Debug options, separated by commas. [env:
COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are
tried. [env: COVERAGE_RCFILE]
.. [[[end]]] (sum: DwG6DxRZIf)
The title of the report can be set with the ``title`` setting in the
``[html]`` section of the configuration file, or the ``--title`` switch on
the command line.
If you prefer a different style for your HTML report, you can provide your
own CSS file to apply, by specifying a CSS file in the ``[html]`` section of
the configuration file. See :ref:`config_html_extra_css` for details.
The ``-d`` argument specifies an output directory, defaulting to "htmlcov"::
$ coverage html -d coverage_html
Other common reporting options are described above in :ref:`cmd_reporting`.
Generating the HTML report can be time-consuming. Stored with the HTML report
is a data file that is used to speed up reporting the next time. If you
generate a new report into the same directory, coverage.py will skip
generating unchanged pages, making the process faster.
The ``--skip-covered`` switch will skip any file with 100% coverage, letting
you focus on the files that still need attention. The ``--skip-empty`` switch
will skip any file with no executable statements.
The ``--precision`` option controls the number of digits displayed after the
decimal point in coverage percentages, defaulting to none.
If you have :ref:`recorded contexts `, the ``--contexts`` option lets
you choose which contexts to report on, and the ``--show-contexts`` option will
annotate lines with the contexts that ran them. See :ref:`context_reporting`
for details.
These options can also be set in your .coveragerc file. See
:ref:`Configuration: [html] `.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_json.rst 0000644 0001751 0001751 00000005356 15073731535 017757 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_json:
JSON reporting: ``coverage json``
---------------------------------
The **json** command writes coverage data to a "coverage.json" file.
.. [[[cog show_help("json") ]]]
.. code::
$ coverage json --help
Usage: coverage json [options] [modules]
Generate a JSON report of coverage results.
Options:
--contexts=REGEX1,REGEX2,...
Only display data from lines covered in the given
contexts. Accepts Python regexes, which must be
quoted.
--data-file=INFILE Read coverage data for report generation from this
file. Defaults to '.coverage'. [env: COVERAGE_FILE]
--fail-under=MIN Exit with a status of 2 if the total coverage is less
than MIN.
-i, --ignore-errors Ignore errors while reading source files.
--include=PAT1,PAT2,...
Include only files whose paths match one of these
patterns. Accepts shell-style wildcards, which must be
quoted.
--omit=PAT1,PAT2,... Omit files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
-o OUTFILE Write the JSON report to this file. Defaults to
'coverage.json'
--pretty-print Format the JSON for human readers.
-q, --quiet Don't print messages about what is happening.
--show-contexts Show contexts for covered lines.
--debug=OPTS Debug options, separated by commas. [env:
COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are
tried. [env: COVERAGE_RCFILE]
.. [[[end]]] (sum: 5T5gy2XZcc)
You can specify the name of the output file with the ``-o`` switch. The JSON
can be nicely formatted by specifying the ``--pretty-print`` switch.
Other common reporting options are described above in :ref:`cmd_reporting`.
These options can also be set in your .coveragerc file. See
:ref:`Configuration: [json] `.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_lcov.rst 0000644 0001751 0001751 00000004334 15073731535 017744 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_lcov:
LCOV reporting: ``coverage lcov``
---------------------------------
The **lcov** command writes coverage data to a "coverage.lcov" file.
.. [[[cog show_help("lcov") ]]]
.. code::
$ coverage lcov --help
Usage: coverage lcov [options] [modules]
Generate an LCOV report of coverage results.
Options:
--data-file=INFILE Read coverage data for report generation from this
file. Defaults to '.coverage'. [env: COVERAGE_FILE]
--fail-under=MIN Exit with a status of 2 if the total coverage is less
than MIN.
-i, --ignore-errors Ignore errors while reading source files.
--include=PAT1,PAT2,...
Include only files whose paths match one of these
patterns. Accepts shell-style wildcards, which must be
quoted.
-o OUTFILE Write the LCOV report to this file. Defaults to
'coverage.lcov'
--omit=PAT1,PAT2,... Omit files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
-q, --quiet Don't print messages about what is happening.
--debug=OPTS Debug options, separated by commas. [env:
COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are
tried. [env: COVERAGE_RCFILE]
.. [[[end]]] (sum: Fqz7roAR0u)
Common reporting options are described above in :ref:`cmd_reporting`.
Also see :ref:`Configuration: [lcov] `.
.. versionadded:: 6.3
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_report.rst 0000644 0001751 0001751 00000014740 15073731535 020316 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_report:
Coverage summary: ``coverage report``
-------------------------------------
The simplest reporting is a textual summary produced with **report**::
$ coverage report
Name Stmts Miss Cover
---------------------------------------------
my_program.py 20 4 80%
my_module.py 15 2 86%
my_other_module.py 56 6 89%
---------------------------------------------
TOTAL 91 12 87%
For each module executed, the report shows the count of executable statements,
the number of those statements missed, and the resulting coverage, expressed
as a percentage.
.. [[[cog show_help("report") ]]]
.. code::
$ coverage report --help
Usage: coverage report [options] [modules]
Report coverage statistics on modules.
Options:
--contexts=REGEX1,REGEX2,...
Only display data from lines covered in the given
contexts. Accepts Python regexes, which must be
quoted.
--data-file=INFILE Read coverage data for report generation from this
file. Defaults to '.coverage'. [env: COVERAGE_FILE]
--fail-under=MIN Exit with a status of 2 if the total coverage is less
than MIN.
--format=FORMAT Output format, either text (default), markdown, or
total.
-i, --ignore-errors Ignore errors while reading source files.
--include=PAT1,PAT2,...
Include only files whose paths match one of these
patterns. Accepts shell-style wildcards, which must be
quoted.
--omit=PAT1,PAT2,... Omit files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
--precision=N Number of digits after the decimal point to display
for reported coverage percentages.
--sort=COLUMN Sort the report by the named column: name, stmts,
miss, branch, brpart, or cover. Default is name.
-m, --show-missing Show line numbers of statements in each module that
weren't executed.
--skip-covered Skip files with 100% coverage.
--no-skip-covered Disable --skip-covered.
--skip-empty Skip files with no code.
--debug=OPTS Debug options, separated by commas. [env:
COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are
tried. [env: COVERAGE_RCFILE]
.. [[[end]]] (sum: FnJyop2efr)
The ``-m`` flag also shows the line numbers of missing statements::
$ coverage report -m
Name Stmts Miss Cover Missing
-------------------------------------------------------
my_program.py 20 4 80% 33-35, 39
my_module.py 15 2 86% 8, 12
my_other_module.py 56 6 89% 17-23
-------------------------------------------------------
TOTAL 91 12 87%
If you are using branch coverage, then branch statistics will be reported in
the Branch and BrPart (for Partial Branch) columns, the Missing column will
detail the missed branches::
$ coverage report -m
Name Stmts Miss Branch BrPart Cover Missing
---------------------------------------------------------------------
my_program.py 20 4 10 2 80% 33-35, 36->38, 39
my_module.py 15 2 3 0 86% 8, 12
my_other_module.py 56 6 5 1 89% 17-23, 40->45
---------------------------------------------------------------------
TOTAL 91 12 18 3 87%
Ranges of lines are shown with a dash: "17-23" means all lines from 17 to 23
inclusive are missing coverage. Missed branches are shown with an arrow:
"40->45" means the branch from line 40 to line 45 is missing. A branch can go
backwards in a file, so you might see a branch from a later line to an earlier
line, like "55->50".
You can restrict the report to only certain files by naming them on the
command line::
$ coverage report -m my_program.py my_other_module.py
Name Stmts Miss Cover Missing
-------------------------------------------------------
my_program.py 20 4 80% 33-35, 39
my_other_module.py 56 6 89% 17-23
-------------------------------------------------------
TOTAL 76 10 87%
The ``--skip-covered`` switch will skip any file with 100% coverage, letting
you focus on the files that still need attention. The ``--no-skip-covered``
option can be used if needed to see all the files. The ``--skip-empty`` switch
will skip any file with no executable statements.
If you have :ref:`recorded contexts `, the ``--contexts`` option lets
you choose which contexts to report on. See :ref:`context_reporting` for
details.
The ``--precision`` option controls the number of digits displayed after the
decimal point in coverage percentages, defaulting to none.
The ``--sort`` option is the name of a column to sort the report by.
The ``--format`` option controls the style of the report. ``--format=text``
creates plain text tables as shown above. ``--format=markdown`` creates
Markdown tables. ``--format=total`` writes out a single number, the total
coverage percentage as shown at the end of the tables, but without a percent
sign.
Other common reporting options are described above in :ref:`cmd_reporting`.
These options can also be set in your .coveragerc file. See
:ref:`Configuration: [report] `.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_reporting.rst 0000644 0001751 0001751 00000003416 15073731535 021012 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_reporting:
Reporting
---------
Coverage.py provides a few styles of reporting, with the
:ref:`report `,
:ref:`html `,
:ref:`json `,
:ref:`lcov `,
:ref:`xml `,
and :ref:`annotate `
commands. They share a number of common options.
The command-line arguments are module or file names to report on if you'd like
to report on a subset of the data collected.
The ``--include`` and ``--omit`` flags specify lists of file name patterns.
They control which files to report on, and are described in more detail in
:ref:`source`.
The ``-i`` or ``--ignore-errors`` switch tells coverage.py to ignore problems
encountered trying to find source files to report on. This can be useful if
some files are missing, or if your Python execution is tricky enough that file
names are synthesized without real source files.
If you provide a ``--fail-under`` value, the total percentage covered will be
compared to that value. If it is less, the command will exit with a status
code of 2, indicating that the total coverage was less than your target. This
can be used as part of a pass/fail condition, for example in a continuous
integration server. This option isn't available for **annotate**.
These options can also be set in your .coveragerc file. See
:ref:`Configuration: [report] `.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_run.rst 0000644 0001751 0001751 00000017204 15073731535 017605 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_run:
Execution: ``coverage run``
---------------------------
You collect execution data by running your Python program with the **run**
command::
$ coverage run my_program.py arg1 arg2
blah blah ..your program's output.. blah blah
Your program runs just as if it had been invoked with the Python command line.
Arguments after your file name are passed to your program as usual in
``sys.argv``. Rather than providing a file name, you can use the ``-m`` switch
and specify an importable module name instead, just as you can with the
Python ``-m`` switch::
$ coverage run -m packagename.modulename arg1 arg2
blah blah ..your program's output.. blah blah
.. note::
In most cases, the program to use here is a test runner, not your program
you are trying to measure. The test runner will run your tests and coverage
will measure the coverage of your code along the way.
There are many options:
.. [[[cog show_help("run") ]]]
.. code::
$ coverage run --help
Usage: coverage run [options] [program options]
Run a Python program, measuring code execution.
Options:
-a, --append Append data to the data file. Otherwise it starts
clean each time.
--branch Measure branch coverage in addition to statement
coverage.
--concurrency=LIBS Properly measure code using a concurrency library.
Valid values are: eventlet, gevent, greenlet,
multiprocessing, thread, or a comma-list of them.
--context=LABEL The context label to record for this coverage run.
--data-file=OUTFILE Write the recorded coverage data to this file.
Defaults to '.coverage'. [env: COVERAGE_FILE]
--include=PAT1,PAT2,...
Include only files whose paths match one of these
patterns. Accepts shell-style wildcards, which must be
quoted.
-m, --module is an importable Python module, not a script
path, to be run as 'python -m' would run it.
--omit=PAT1,PAT2,... Omit files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
-L, --pylib Measure coverage even inside the Python installed
library, which isn't done by default.
-p, --parallel-mode Append a unique suffix to the data file name to
collect separate data from multiple processes.
--save-signal=SIGNAL Specify a signal that will trigger coverage to write
its collected data. Supported values are: USR1, USR2.
Not available on Windows.
--source=SRC1,SRC2,...
A list of directories or importable names of code to
measure.
--timid Use the slower Python trace function core.
--debug=OPTS Debug options, separated by commas. [env:
COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are
tried. [env: COVERAGE_RCFILE]
.. [[[end]]] (sum: YwMI03MDmQ)
Many of these options can also be set in the :ref:`config_run` section of your
configuration file. Remember to put options for run after "run", but before
the program invocation::
$ coverage run --source=dir1,dir2 my_program.py arg1 arg2
$ coverage run --source=dir1,dir2 -m packagename.modulename arg1 arg2
If you want :ref:`branch coverage ` measurement, use the ``--branch``
flag. Otherwise only statement coverage is measured.
You can specify the code to measure with the ``--source``, ``--include``, and
``--omit`` switches. See :ref:`Specifying source files ` for
details of their interpretation.
.. note::
Specifying ``--source`` on the ``coverage run`` command line won't affect
subsequent reporting commands like ``coverage xml``. Use the :ref:`source
` setting in the configuration file to apply the setting
uniformly to all commands.
Coverage.py can measure multi-threaded programs by default. If you are using
more other concurrency support, with the `multiprocessing`_, `greenlet`_,
`eventlet`_, or `gevent`_ libraries, then coverage.py can get confused. Use the
``--concurrency`` switch to properly measure programs using these libraries.
Give it a value of ``multiprocessing``, ``thread``, ``greenlet``, ``eventlet``,
or ``gevent``. Values other than ``thread`` require the :ref:`C extension
`.
You can combine multiple values for ``--concurrency``, separated with commas.
You can specify ``thread`` and also one of ``eventlet``, ``gevent``, or
``greenlet``.
If you are using ``--concurrency=multiprocessing``, you must set your other
options in the configuration file. Options on the command line will not be
passed to the processes that multiprocessing creates. Best practice is to use
the configuration file for all options.
.. _multiprocessing: https://docs.python.org/3/library/multiprocessing.html
.. _greenlet: https://greenlet.readthedocs.io/
.. _gevent: https://www.gevent.org/
.. _eventlet: https://eventlet.readthedocs.io/
If you are measuring coverage in a multi-process program, or across a number of
machines, you'll want the ``--parallel-mode`` switch to keep the data separate
during measurement. See :ref:`cmd_combine` below.
You can specify a :ref:`static context ` for a coverage run with
``--context``. This can be any label you want, and will be recorded with the
data. See :ref:`contexts` for more information.
By default, coverage.py does not measure code installed with the Python
interpreter, for example, the standard library. If you want to measure that
code as well as your own, add the ``-L`` (or ``--pylib``) flag.
If your coverage results seem to be overlooking code that you know has been
executed, try running coverage.py again with the ``--timid`` flag. This uses a
simpler but slower trace method, and might be needed in rare cases.
If you are specifying ``--save-signal``, please make sure that your program
doesn't intercept this signal. If it does, coverage won't receive the signal
and the data file will not be written.
.. versionadded:: 7.10 ``--save-signal``
Coverage.py sets an environment variable, ``COVERAGE_RUN`` to indicate that
your code is running under coverage measurement. The value is not relevant,
and may change in the future.
.. _cmd_datafile:
Data file
.........
Coverage.py collects execution data in a file called ".coverage". If need be,
you can set a new file name with the ``COVERAGE_FILE`` environment variable.
This can include a path to another directory.
By default, each run of your program starts with an empty data set. If you need
to run your program multiple times to get complete data (for example, because
you need to supply different options), you can accumulate data across runs with
the ``--append`` flag on the **run** command.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/cmd_xml.rst 0000644 0001751 0001751 00000006001 15073731535 017572 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to insert the latest command help into the
docs. If it's out of date, the quality checks will fail. Running "make
prebuild" will bring it up to date.
.. [[[cog
from cog_helpers import show_help
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _cmd_xml:
XML reporting: ``coverage xml``
-------------------------------
The **xml** command writes coverage data to a "coverage.xml" file in a format
compatible with `Cobertura`_.
.. _Cobertura: http://cobertura.github.io/cobertura/
.. [[[cog show_help("xml") ]]]
.. code::
$ coverage xml --help
Usage: coverage xml [options] [modules]
Generate an XML report of coverage results.
Options:
--data-file=INFILE Read coverage data for report generation from this
file. Defaults to '.coverage'. [env: COVERAGE_FILE]
--fail-under=MIN Exit with a status of 2 if the total coverage is less
than MIN.
-i, --ignore-errors Ignore errors while reading source files.
--include=PAT1,PAT2,...
Include only files whose paths match one of these
patterns. Accepts shell-style wildcards, which must be
quoted.
--omit=PAT1,PAT2,... Omit files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
-o OUTFILE Write the XML report to this file. Defaults to
'coverage.xml'
-q, --quiet Don't print messages about what is happening.
--skip-empty Skip files with no code.
--debug=OPTS Debug options, separated by commas. [env:
COVERAGE_DEBUG]
-h, --help Get help on this command.
--rcfile=RCFILE Specify configuration file. By default '.coveragerc',
'setup.cfg', 'tox.ini', and 'pyproject.toml' are
tried. [env: COVERAGE_RCFILE]
.. [[[end]]] (sum: iyOdiVNL4L)
You can specify the name of the output file with the ``-o`` switch.
Other common reporting options are described above in :ref:`cmd_reporting`.
To include complete file paths in the output file, rather than just
the file name, use [include] vs [source] in your ".coveragerc" file.
For example, use this:
.. code:: ini
[run]
include =
foo/*
bar/*
which will result in
.. code:: xml
in place of this:
.. code:: ini
[run]
source =
foo
bar
which may result in
.. code:: xml
These options can also be set in your .coveragerc file. See
:ref:`Configuration: [xml] `.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/commands/index.rst 0000644 0001751 0001751 00000005113 15073731535 017261 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _cmd:
========
Commands
========
.. highlight:: console
When you install coverage.py, a command-line script called ``coverage`` is
placed on your path. To help with multi-version installs, it will also create
a ``coverage3`` alias, and a ``coverage-X.Y`` alias, depending on the version
of Python you're using. For example, when installing on Python 3.10, you will
be able to use ``coverage``, ``coverage3``, or ``coverage-3.10`` on the command
line.
Coverage.py has a number of commands:
* **run** -- :ref:`Run a Python program and collect execution data `.
* **combine** -- :ref:`Combine together a number of data files `.
* **erase** -- :ref:`Erase previously collected coverage data `.
* **report** -- :ref:`Report coverage results `.
* **html** --
:ref:`Produce annotated HTML listings with coverage results `.
* **xml** -- :ref:`Produce an XML report with coverage results `.
* **json** -- :ref:`Produce a JSON report with coverage results `.
* **lcov** -- :ref:`Produce an LCOV report with coverage results `.
* **annotate** --
:ref:`Annotate source files with coverage results `.
* **debug** -- :ref:`Get diagnostic information `.
Global options
--------------
Help is available with the **help** command, or with the ``--help`` switch on
any other command::
$ coverage help
$ coverage help run
$ coverage run --help
Version information for coverage.py can be displayed with
``coverage --version``:
.. parsed-literal::
$ coverage --version
Coverage.py, version |release| with C extension
Documentation at |doc-url|
Any command can use a configuration file by specifying it with the
``--rcfile=FILE`` command-line switch. Any option you can set on the command
line can also be set in the configuration file. This can be a better way to
control coverage.py since the configuration file can be checked into source
control, and can provide options that other invocation techniques (like test
runner plugins) may not offer. See :ref:`config` for more details.
For diagnosing problems, commands accept a ``--debug`` option. See
:ref:`cmd_run_debug`.
Commands
--------
The details of each command are on these pages:
.. toctree::
:maxdepth: 1
cmd_run
cmd_combine
cmd_erase
cmd_reporting
cmd_report
cmd_html
cmd_xml
cmd_json
cmd_lcov
cmd_annotate
cmd_debug
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/conf.py 0000644 0001751 0001751 00000020521 15073731535 015116 0 ustar 00runner runner # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
"""Sphinx configuration."""
# coverage.py documentation build configuration file, created by
# sphinx-quickstart on Wed May 13 22:18:33 2009.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import atexit
import os
import re
import sys
import tempfile
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.append(os.path.abspath('.'))
# on_rtd is whether we are on readthedocs.org
on_rtd = os.getenv("READTHEDOCS") == "True"
# -- General configuration -----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.todo",
"sphinx.ext.ifconfig",
"sphinx.ext.intersphinx",
"sphinxcontrib.restbuilder",
"sphinx.ext.napoleon",
"sphinxext.rediraffe",
"sphinx_code_tabs",
"sphinx_rtd_theme",
]
autodoc_typehints = "description"
# Add any paths that contain templates here, relative to this directory.
templates_path = []
# The suffix of source filenames.
source_suffix = {".rst": "restructuredtext"}
# The encoding of source files.
# source_encoding = 'utf-8'
# The master toctree document.
master_doc = "index"
# General information about the project.
project = "Coverage.py"
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
# @@@ editable
copyright = "2009โ2025, Ned Batchelder" # pylint: disable=redefined-builtin
# The short X.Y.Z version.
version = "7.11.0"
# The full version, including alpha/beta/rc tags.
release = "7.11.0"
# The date of release, in "monthname day, year" format.
release_date = "October 15, 2025"
# @@@ end
rst_epilog = f"""
.. |release_date| replace:: {release_date}
.. |coverage-equals-release| replace:: coverage=={release}
.. |doc-url| replace:: https://coverage.readthedocs.io/en/{release}
.. |br| raw:: html
"""
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of documents that shouldn't be included in the build.
# unused_docs = []
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_patterns = ["_build", "help/*"]
# The reST default role (used for this markup: `text`) to use for all documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
}
rediraffe_branch = "origin/master"
rediraffe_redirects = {
"cmd.rst": "commands/index.rst",
}
nitpick_ignore = [
("py:class", "DefaultValue"),
("py:class", "FilePath"),
("py:class", "types.FrameType"),
("py:class", "TWarnFn"),
("py:class", "TDebugCtl"),
]
nitpick_ignore_regex = [
(r"py:class", r"coverage\..*\..*"),
]
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# html_style = "neds.css"
# html_add_permalinks = ""
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = ['_templates']
# The name for this set of Sphinx documents. If None, it defaults to
# " v documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = "media/sleepy-snake-circle-150.png"
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y'
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
html_use_modindex = False
# If false, no index is generated.
html_use_index = False
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
html_show_sourcelink = False
# If true, an OpenSearch description file will be output, and all pages will
# contain a tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = '.htm'
# Output file base name for HTML help builder.
htmlhelp_basename = "coveragepydoc"
# -- Spelling ---
if any("spell" in arg for arg in sys.argv):
# sphinxcontrib.spelling needs the native "enchant" library, which often is
# missing, so only use the extension if we are specifically spell-checking.
extensions += ["sphinxcontrib.spelling"]
names_file = tempfile.NamedTemporaryFile(mode="w", prefix="coverage_names_", suffix=".txt")
with open("../CONTRIBUTORS.txt", encoding="utf-8") as contributors:
names = set(re.split(r"[^\w']", contributors.read()))
names = [n for n in names if len(n) >= 2 and n[0].isupper()]
names_file.write("\n".join(names))
names_file.flush()
atexit.register(os.remove, names_file.name)
spelling_word_list_filename = ["dict.txt", names_file.name]
spelling_show_suggestions = False
# Regexes for URLs that linkcheck should skip.
linkcheck_ignore = [
# We have lots of links to GitHub, and they start refusing to serve them to linkcheck,
# so don't bother checking them.
r"https://github.com/nedbat/coveragepy/(issues|pull)/\d+",
# When publishing a new version, the docs will refer to the version before
# the docs have been published. So don't check those links.
rf"https://coverage.readthedocs.io/en/{release}$",
]
# https://github.com/executablebooks/sphinx-tabs/pull/54
sphinx_tabs_valid_builders = ["linkcheck"]
# When auto-doc'ing a class, only write the class' docstring into the class docs,
# don't automatically include the __init__ docstring.
autoclass_content = "class"
prerelease = bool(max(release).isalpha())
def setup(app):
"""Configure Sphinx"""
app.add_css_file("coverage.css")
app.add_config_value("prerelease", False, "env")
print(f"** Prerelease = {prerelease!r}")
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/config.rst 0000644 0001751 0001751 00000066734 15073731535 015636 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to create the tabbed multi-syntax
configuration examples. If those are wrong, the quality checks will fail.
Running "make prebuild" checks them and produces the output.
.. [[[cog
from cog_helpers import show_configs
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _config:
=======================
Configuration reference
=======================
.. highlight:: ini
Coverage.py options can be specified in a configuration file. This makes it
easier to re-run coverage.py with consistent settings, and also allows for
specification of options that are otherwise only available in the
:ref:`API `.
Configuration files also make it easier to get coverage testing of spawned
subprocesses. See :ref:`subprocess` for more details.
The default name for the configuration file is ``.coveragerc``, in the same
directory coverage.py is being run in. Most of the settings in the
configuration file are tied to your source code and how it should be measured,
so it should be stored with your source, and checked into source control,
rather than put in your home directory.
A different location for the configuration file can be specified with the
``--rcfile=FILE`` command line option or with the ``COVERAGE_RCFILE``
environment variable.
If ``.coveragerc`` doesn't exist and another file hasn't been specified, then
coverage.py will look for settings in other common configuration files, in this
order: setup.cfg, tox.ini, or pyproject.toml. The first file found with
coverage.py settings will be used and other files won't be consulted.
Coverage.py will read from "pyproject.toml" if TOML support is available,
either because you are running on Python 3.11 or later, or because you
installed with the ``toml`` extra (``pip install coverage[toml]``).
Syntax
------
The specific syntax of a configuration file depends on what type it is.
All configuration files are assumed to be in INI format, unless their file
extension is .toml, which are TOML.
INI Syntax
..........
A coverage.py configuration file is in classic .ini file format: sections are
introduced by a ``[section]`` header, and contain ``name = value`` entries.
Lines beginning with ``#`` or ``;`` are ignored as comments.
Strings don't need quotes. Multi-valued strings can be created by indenting
values on multiple lines.
Boolean values can be specified as ``on``, ``off``, ``true``, ``false``, ``1``,
or ``0`` and are case-insensitive.
In setup.cfg or tox.ini, the section names have "coverage:" prefixed, so the
``[run]`` options described below will be found in the ``[coverage:run]``
section of the file.
TOML Syntax
...........
`TOML syntax`_ uses explicit lists with brackets, and strings with quotes.
Booleans are ``true`` or ``false``.
Configuration must be within the ``[tool.coverage]`` section, for example,
``[tool.coverage.run]``. Environment variable expansion in values is
available, but only within quoted strings, even for non-string values.
.. _TOML syntax: https://toml.io
Environment variables
.....................
Environment variables can be substituted in by using dollar signs: ``$WORD``
or ``${WORD}`` will be replaced with the value of ``WORD`` in the environment.
A dollar sign can be inserted with ``$$``. Special forms can be used to
control what happens if the variable isn't defined in the environment:
- If you want to raise an error if an environment variable is undefined, use a
question mark suffix: ``${WORD?}``.
- If you want to provide a default for missing variables, use a dash with a
default value: ``${WORD-default value}``.
- Otherwise, missing environment variables will result in empty strings with no
error.
Sample file
...........
Here's a sample configuration file, in each syntax:
.. [[[cog
show_configs(
ini=r"""
[run]
branch = True
[report]
; Regexes for lines to exclude from consideration
exclude_also =
; Don't complain about missing debug-only code:
def __repr__
if self\.debug
; Don't complain if tests don't hit defensive assertion code:
raise AssertionError
raise NotImplementedError
; Don't complain if non-runnable code isn't run:
if 0:
if __name__ == .__main__.:
; Don't complain about abstract methods, they aren't run:
@(abc\.)?abstractmethod
ignore_errors = True
[html]
directory = coverage_html_report
""",
toml=r"""
[tool.coverage.run]
branch = true
[tool.coverage.report]
# Regexes for lines to exclude from consideration
exclude_also = [
# Don't complain about missing debug-only code:
"def __repr__",
"if self\\.debug",
# Don't complain if tests don't hit defensive assertion code:
"raise AssertionError",
"raise NotImplementedError",
# Don't complain if non-runnable code isn't run:
"if 0:",
"if __name__ == .__main__.:",
# Don't complain about abstract methods, they aren't run:
"@(abc\\.)?abstractmethod",
]
ignore_errors = true
[tool.coverage.html]
directory = "coverage_html_report"
""",
)
.. ]]]
.. tabs::
.. code-tab:: ini
:caption: .coveragerc
[run]
branch = True
[report]
; Regexes for lines to exclude from consideration
exclude_also =
; Don't complain about missing debug-only code:
def __repr__
if self\.debug
; Don't complain if tests don't hit defensive assertion code:
raise AssertionError
raise NotImplementedError
; Don't complain if non-runnable code isn't run:
if 0:
if __name__ == .__main__.:
; Don't complain about abstract methods, they aren't run:
@(abc\.)?abstractmethod
ignore_errors = True
[html]
directory = coverage_html_report
.. code-tab:: toml
:caption: pyproject.toml
[tool.coverage.run]
branch = true
[tool.coverage.report]
# Regexes for lines to exclude from consideration
exclude_also = [
# Don't complain about missing debug-only code:
"def __repr__",
"if self\\.debug",
# Don't complain if tests don't hit defensive assertion code:
"raise AssertionError",
"raise NotImplementedError",
# Don't complain if non-runnable code isn't run:
"if 0:",
"if __name__ == .__main__.:",
# Don't complain about abstract methods, they aren't run:
"@(abc\\.)?abstractmethod",
]
ignore_errors = true
[tool.coverage.html]
directory = "coverage_html_report"
.. code-tab:: ini
:caption: setup.cfg or tox.ini
[coverage:run]
branch = True
[coverage:report]
; Regexes for lines to exclude from consideration
exclude_also =
; Don't complain about missing debug-only code:
def __repr__
if self\.debug
; Don't complain if tests don't hit defensive assertion code:
raise AssertionError
raise NotImplementedError
; Don't complain if non-runnable code isn't run:
if 0:
if __name__ == .__main__.:
; Don't complain about abstract methods, they aren't run:
@(abc\.)?abstractmethod
ignore_errors = True
[coverage:html]
directory = coverage_html_report
.. [[[end]]] (sum: HU1Z62mvRK)
The specific configuration settings are described below. Many sections and
settings correspond roughly to commands and options in the :ref:`command-line
interface `.
.. _config_run:
[run]
-----
These settings are generally used when running product code, though some apply
to more than one command.
.. _config_run_branch:
[run] branch
............
(boolean, default False) Whether to measure :ref:`branch coverage ` in
addition to statement coverage.
.. _config_run_command_line:
[run] command_line
..................
(string) The command-line to run your program. This will be used if you run
``coverage run`` with no further arguments. Coverage.py options cannot be
specified here, other than ``-m`` to indicate the module to run.
.. versionadded:: 5.0
.. _config_run_concurrency:
[run] concurrency
.................
(multi-string, default "thread") The concurrency libraries in use by the
product code. If your program uses `multiprocessing`_, `gevent`_, `greenlet`_,
or `eventlet`_, you must name that library in this option, or coverage.py will
produce very wrong results.
.. _multiprocessing: https://docs.python.org/3/library/multiprocessing.html
.. _greenlet: https://greenlet.readthedocs.io/
.. _gevent: https://www.gevent.org/
.. _eventlet: https://eventlet.readthedocs.io/
See :ref:`subprocess` for details of multi-process measurement.
Before version 4.2, this option only accepted a single string.
.. versionadded:: 4.0
.. _config_run_context:
[run] context
.............
(string) The static context to record for this coverage run. See
:ref:`contexts` for more information
.. versionadded:: 5.0
.. _config_run_core:
[run] core
..........
(string) Specify which trace function implementation to use. Valid values are:
"pytrace" for the pure Python implementation, "ctrace" for the C implementation
(default), or "sysmon" for the :mod:`sys.monitoring `
implementation (Python 3.12+ only).
This was previously only available as the COVERAGE_CORE environment variable.
Note that the "sysmon" core does not yet support plugins or dynamic contexts.
.. versionadded:: 7.9
.. _config_run_cover_pylib:
[run] cover_pylib
.................
(boolean, default False) Whether to measure the Python standard library.
.. _config_run_data_file:
[run] data_file
...............
(string, default ".coverage") The name of the data file to use for storing or
reporting coverage. This value can include a path to another directory.
.. _config_run_disable_warnings:
[run] disable_warnings
......................
(multi-string) A list of warnings to disable. Warnings that can be disabled
include a short string at the end, the name of the warning. See
:ref:`cmd_warnings` for specific warnings.
.. _config_run_debug:
[run] debug
...........
(multi-string) A list of debug options. See :ref:`the run --debug option
` for details.
.. _config_run_debug_file:
[run] debug_file
................
(string) A file name to write debug output to. See :ref:`the run --debug
option ` for details.
.. _config_run_dynamic_context:
[run] dynamic_context
.....................
(string) The name of a strategy for setting the dynamic context during
execution. See :ref:`dynamic_contexts` for details.
.. _config_run_include:
[run] include
.............
(multi-string) A list of file name patterns, the files to include in
measurement or reporting. Ignored if ``source`` is set. See :ref:`source` for
details.
.. _config_run_omit:
[run] omit
..........
(multi-string) A list of file name patterns, the files to leave out of
measurement or reporting. See :ref:`source` for details.
.. _config_run_parallel:
[run] parallel
..............
(boolean, default False) Append the machine name, process id and random number
to the data file name to simplify collecting data from many processes. See
:ref:`cmd_combine` for more information.
.. _config_run_patch:
[run] patch
...........
(multi-string) A list of patch names that coverage can apply to the runtime
environment to improve coverage measurement. The available patches correspond
to Python features that could interfere with coverage. The patch inserts
coverage-specific code to collect the correct data.
These must be requested in the configuration instead of being applied
automatically because they could be invasive and produce undesirable
side-effects.
Available patches:
- ``execv``: The :func:`execv ` family of functions end the
current program without giving coverage a chance to write collected data.
This patch adjusts those functions to save the data before starting the next
executable. Not available on Windows.
- ``_exit``: The :func:`os._exit() ` function exits the
process immediately without calling cleanup handlers. This patch saves
coverage data before exiting.
- ``fork``: Forking a process normally continues measuring coverage properly.
This patch stops the previous coverage and starts a new one in the child
process for those times when the default handling isn't enough.
- ``subprocess``: Python sub-processes normally won't get coverage measurement.
This patch configures Python to start coverage automatically, and will apply
to processes created with :mod:`subprocess`, :func:`os.system`, or one of the
:func:`execv ` or :func:`spawnv ` family
of functions. If an ``exec*e`` or ``spawn*e`` function is used, the new
environment must copy over the ``COVERAGE_PROCESS_START`` environment
variable.
The ``subprocess`` patch sets :ref:`parallel = True `
and will require combining data files before reporting. See
:ref:`cmd_combine` for more details.
.. versionadded:: 7.10
.. _config_run_plugins:
[run] plugins
.............
(multi-string) A list of plugin package names. See :ref:`plugins` for more
information.
.. _config_run_relative_files:
[run] relative_files
....................
(boolean, default False) store relative file paths in the data file. This
makes it easier to measure code in one (or multiple) environments, and then
report in another. See :ref:`cmd_combine` for details.
Note that setting ``source`` has to be done in the configuration file rather
than the command line for this option to work, since the reporting commands
need to know the source origin.
.. versionadded:: 5.0
.. _config_run_sigterm:
[run] sigterm
.............
(boolean, default False) if true, register a SIGTERM signal handler to capture
data when the process ends due to a SIGTERM signal. This includes
:meth:`Process.terminate ` and other
ways to terminate a process. This can help when collecting data in usual
situations, but can also introduce problems (see `issue 1310`_).
The signal handler is only registered on Linux and Mac. On Windows, this
setting has no effect.
.. _issue 1310: https://github.com/nedbat/coveragepy/issues/1310
.. versionadded:: 6.4 (in 6.3 this was always enabled)
.. _config_run_source:
[run] source
............
(multi-string) A list of packages or directories, the source to measure during
execution. If set, ``include`` is ignored. See :ref:`source` for details.
.. _config_run_source_pkgs:
[run] source_pkgs
.................
(multi-string) A list of packages, the source to measure during execution.
Operates the same as ``source``, but only names packages, for resolving
ambiguities between packages and directories.
.. versionadded:: 5.3
.. _config_run_source_dirs:
[run] source_dirs
.................
(multi-string) A list of directories, the source to measure during execution.
Operates the same as ``source``, but only names directories, for resolving
ambiguities between packages and directories.
.. versionadded:: 7.8
.. _config_run_timid:
[run] timid
...........
(boolean, default False) Use a simpler but slower trace method. This uses the
PyTracer trace function core instead of CTracer, and is only needed in very
unusual circumstances.
.. _config_paths:
[paths]
-------
The entries in this section are lists of file paths that should be considered
equivalent when combining data from different machines:
.. [[[cog
show_configs(
ini=r"""
[paths]
source =
src/
/jenkins/build/*/src
c:\myproj\src
""",
toml=r"""
[tool.coverage.paths]
source = [
"src/",
"/jenkins/build/*/src",
"c:\\myproj\\src",
]
""",
)
.. ]]]
.. tabs::
.. code-tab:: ini
:caption: .coveragerc
[paths]
source =
src/
/jenkins/build/*/src
c:\myproj\src
.. code-tab:: toml
:caption: pyproject.toml
[tool.coverage.paths]
source = [
"src/",
"/jenkins/build/*/src",
"c:\\myproj\\src",
]
.. code-tab:: ini
:caption: setup.cfg or tox.ini
[coverage:paths]
source =
src/
/jenkins/build/*/src
c:\myproj\src
.. [[[end]]] (sum: oHSl8SGiMT)
The names of the entries ("source" in this example) are ignored, you may choose
any name that you like. The value is a list of strings. When combining data
with the ``combine`` command, two file paths will be combined if they start
with paths from the same list.
The first value must be an actual file path on the machine where the reporting
will happen, so that source code can be found. The other values can be file
patterns to match against the paths of collected data, or they can be absolute
or relative file paths on the current machine.
In this example, data collected for "/jenkins/build/1234/src/module.py" will be
combined with data for "c:\\myproj\\src\\module.py", and will be reported
against the source file found at "src/module.py".
If you specify more than one list of paths, they will be considered in order.
A file path will only be remapped if the result exists. If a path matches a
list, but the result doesn't exist, the next list will be tried. The first
list that has an existing result will be used.
Remapping will also be done during reporting, but only within the single data
file being reported. Combining multiple files requires the ``combine``
command.
The ``--debug=pathmap`` option can be used to log details of the re-mapping of
paths. See :ref:`the --debug option `.
See :ref:`cmd_combine_remapping` and :ref:`source_glob` for more information.
.. _config_report:
[report]
--------
Settings common to many kinds of reporting.
.. _config_report_exclude_also:
[report] exclude_also
.....................
(multi-string) A list of regular expressions. This setting is similar to
:ref:`config_report_exclude_lines`: it specifies patterns for lines to exclude
from reporting. This setting is preferred, because it will preserve the
default exclude patterns like ``pragma: no cover`` instead of overwriting them.
See :ref:`config_report_exclude_lines` for further details.
.. versionadded:: 7.2.0
.. _config_report_exclude_lines:
[report] exclude_lines
......................
(multi-string) A list of regular expressions. Any line of your source code
containing a match for one of these regexes is excluded from being reported as
missing. More details are in :ref:`excluding`. If you use this option, you
are replacing all the exclude regexes, so you'll need to also supply the
"pragma: no cover" regex if you still want to use it. The
:ref:`config_report_exclude_also` setting can be used to specify patterns
without overwriting the default set.
You can exclude lines introducing blocks, and the entire block is excluded. If
you exclude a ``def`` line or decorator line, the entire function is excluded.
Be careful when writing this setting: the values are regular expressions that
only have to match a portion of the line. For example, if you write ``...``,
you'll exclude any line with three or more of any character. If you write
``pass``, you'll also exclude the line ``my_pass="foo"``, and so on.
All of the regexes here and in :ref:`config_report_exclude_also` are combined
into one regex for processing, so you cannot use global flags like ``(?s)`` in
your regexes. Use the scoped flag form instead: ``(?s:...)``
.. _config_report_fail_under:
[report] fail_under
...................
(float) A target coverage percentage. If the total coverage measurement is
under this value, then exit with a status code of 2. If you specify a
non-integral value, you must also set ``[report] precision`` properly to make
use of the decimal places. A setting of 100 will fail any value under 100,
regardless of the number of decimal places of precision.
.. _config_report_format:
[report] format
...............
(string, default "text") The format to use for the textual report. The default
is "text" which produces a simple textual table. You can use "markdown" to
produce a Markdown table, or "total" to output only the total coverage
percentage.
.. versionadded:: 7.0
.. _config_report_ignore_errors:
[report] ignore_errors
......................
(boolean, default False) Ignore source code that can't be found, emitting a
warning instead of an exception.
.. _config_report_include:
[report] include
................
(multi-string) A list of file name patterns, the files to include in reporting.
See :ref:`source` for details.
.. _config_include_namespace_packages:
[report] include_namespace_packages
...................................
(boolean, default False) When searching for completely un-executed files,
include directories without ``__init__.py`` files. These are `implicit
namespace packages`_, and are usually skipped.
.. _implicit namespace packages: https://peps.python.org/pep-0420/
.. versionadded:: 7.0
.. _config_report_omit:
[report] omit
.............
(multi-string) A list of file name patterns, the files to leave out of
reporting. See :ref:`source` for details.
.. _config_report_partial_also:
[report] partial_also
.....................
(multi-string) A list of regular expressions. This setting is similar to
:ref:`config_report_partial_branches`: it specifies patterns for branches to
consider fully covered even if they don't exercise both destinations. This
setting is preferred, because it will preserve the default exclude patterns
like ``pragma: no branch`` instead of overwriting them.
See :ref:`config_report_partial_branches` for further details.
.. versionadded:: 7.10.0
.. _config_report_partial_branches:
[report] partial_branches
.........................
(multi-string) A list of regular expressions. Any line of code that matches
one of these regexes is excused from being reported as a partial branch. More
details are in :ref:`branch`. If you use this option, you are replacing all
the partial branch regexes so you'll need to also supply the "pragma: no
branch" regex if you still want to use it. The
:ref:`config_report_partial_also` setting can be used to specify patterns
without overwriting the default set.
.. _config_report_precision:
[report] precision
..................
(integer) The number of digits after the decimal point to display for reported
coverage percentages. The default is 0, displaying for example "87%". A value
of 2 will display percentages like "87.32%". This setting also affects the
interpretation of the ``fail_under`` setting.
.. _config_report_show_missing:
[report] show_missing
.....................
(boolean, default False) When running a summary report, show missing lines.
See :ref:`cmd_report` for more information.
.. _config_report_skip_covered:
[report] skip_covered
.....................
(boolean, default False) Don't report files that are 100% covered. This helps
you focus on files that need attention.
.. _config_report_skip_empty:
[report] skip_empty
...................
(boolean, default False) Don't report files that have no executable code (such
as ``__init__.py`` files).
.. _config_report_sort:
[report] sort
.............
(string, default "Name") Sort the text report by the named column. Allowed
values are "Name", "Stmts", "Miss", "Branch", "BrPart", or "Cover". Prefix
with ``-`` for descending sort (for example, "-cover").
.. _config_html:
[html]
------
Settings particular to HTML reporting. The settings in the ``[report]``
section also apply to HTML output, where appropriate.
.. _config_html_directory:
[html] directory
................
(string, default "htmlcov") Where to write the HTML report files.
.. _config_html_extra_css:
[html] extra_css
................
(string) The path to a file of CSS to apply to the HTML report. The file will
be copied into the HTML output directory. Don't name it "style.css". This CSS
is in addition to the CSS normally used, though you can overwrite as many of
the rules as you like.
.. _config_html_show_context:
[html] show_contexts
....................
(boolean) Should the HTML report include an indication on each line of which
contexts executed the line. See :ref:`dynamic_contexts` for details.
.. _config_html_skip_covered:
[html] skip_covered
...................
(boolean, defaulted from ``[report] skip_covered``) Don't include files in the
report that are 100% covered files. See :ref:`cmd_report` for more information.
.. versionadded:: 5.4
.. _config_html_skip_empty:
[html] skip_empty
.................
(boolean, defaulted from ``[report] skip_empty``) Don't include empty files
(those that have 0 statements) in the report. See :ref:`cmd_report` for more
information.
.. versionadded:: 5.4
.. _config_html_title:
[html] title
............
(string, default "Coverage report") The title to use for the report.
Note this is text, not HTML.
.. _config_xml:
[xml]
-----
Settings particular to XML reporting. The settings in the ``[report]`` section
also apply to XML output, where appropriate.
.. _config_xml_output:
[xml] output
............
(string, default "coverage.xml") Where to write the XML report.
.. _config_xml_package_depth:
[xml] package_depth
...................
(integer, default 99) Controls which directories are identified as packages in
the report. Directories deeper than this depth are not reported as packages.
The default is that all directories are reported as packages.
.. _config_json:
[json]
------
Settings particular to JSON reporting. The settings in the ``[report]``
section also apply to JSON output, where appropriate.
.. versionadded:: 5.0
.. _config_json_output:
[json] output
.............
(string, default "coverage.json") Where to write the JSON file.
.. _config_json_pretty_print:
[json] pretty_print
...................
(boolean, default false) Controls if the JSON is outputted with white space
formatted for human consumption (True) or for minimum file size (False).
.. _config_json_show_contexts:
[json] show_contexts
....................
(boolean, default false) Should the JSON report include an indication of which
contexts executed each line. See :ref:`dynamic_contexts` for details.
.. _config_lcov:
[lcov]
------
Settings particular to LCOV reporting (see :ref:`cmd_lcov`).
.. versionadded:: 6.3
.. _config_lcov_output:
[lcov] output
.............
(string, default "coverage.lcov") Where to write the LCOV file.
.. _config_lcov_line_checksums:
[lcov] line_checksums
.....................
(boolean, default false) Whether to write per-line checksums as part of the
lcov file. Because these checksums cover only lines with actual code on
them, and do not verify the ordering of lines, they provide only a weak
assurance that the source code available to analysis tools (e.g. ``genhtml``)
matches the code that was used to generate the coverage data.
.. versionadded:: 7.6.2
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/contexts.rst 0000644 0001751 0001751 00000011262 15073731535 016222 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to create the tabbed multi-syntax
configuration examples. If those are wrong, the quality checks will fail.
Running "make prebuild" checks them and produces the output.
.. [[[cog
from cog_helpers import show_configs
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _contexts:
====================
Measurement contexts
====================
.. versionadded:: 5.0
Coverage.py measures whether code was run, but it can also record the context
in which it was run. This can provide more information to help you understand
the behavior of your tests.
There are two kinds of context: static and dynamic. Static contexts are fixed
for an entire run, and are set explicitly with an option. Dynamic contexts
change over the course of a single run.
.. _static_contexts:
Static contexts
---------------
A static context is set by an option when you run coverage.py. The value is
fixed for the duration of a run. They can be any text you like, for example,
"python3" or "with_numpy". The context is recorded with the data.
When you :ref:`combine multiple data files ` together, they can
have differing contexts. All of the information is retained, so that the
different contexts are correctly recorded in the combined file.
A static context is specified with the ``--context=CONTEXT`` option to
:ref:`the coverage run command `, or the ``[run] context`` setting in
the configuration file.
.. _dynamic_contexts:
Dynamic contexts
----------------
Dynamic contexts are found during execution. They are most commonly used to
answer the question "what test ran this line?," but have been generalized to
allow any kind of context tracking. As execution proceeds, the dynamic context
changes to record the context of execution. Separate data is recorded for each
context, so that it can be analyzed later.
There are three ways to enable dynamic contexts:
* you can set the ``[run] dynamic_context`` option in your .coveragerc file, or
* you can enable a :ref:`dynamic context switcher `
plugin, or
* another tool (such as a test runner) can call the
:meth:`.Coverage.switch_context` method to set the context explicitly.
The pytest plugin `pytest-cov`_ has a ``--cov-context`` option that uses this
to set the dynamic context for each test.
.. _pytest-cov: https://pypi.org/project/pytest-cov/
.. highlight:: ini
The ``[run] dynamic_context`` setting has only one option now. Set it to
``test_function`` to start a new dynamic context for every test function:
.. [[[cog
show_configs(
ini=r"""
[run]
dynamic_context = test_function
""",
toml=r"""
[tool.coverage.run]
dynamic_context = "test_function"
""",
)
.. ]]]
.. tabs::
.. code-tab:: ini
:caption: .coveragerc
[run]
dynamic_context = test_function
.. code-tab:: toml
:caption: pyproject.toml
[tool.coverage.run]
dynamic_context = "test_function"
.. code-tab:: ini
:caption: setup.cfg or tox.ini
[coverage:run]
dynamic_context = test_function
.. [[[end]]] (sum: dZTDYjHw71)
Each test function you run will be considered a separate dynamic context, and
coverage data will be segregated for each. A test function is any function
whose name starts with "test".
If you have both a static context and a dynamic context, they are joined with a
pipe symbol to be recorded as a single string.
Initially, when your program starts running, the dynamic context is an empty
string. Any code measured before a dynamic context is set will be recorded in
this empty context. For example, if you are recording test names as contexts,
then the code run by the test runner before (and between) tests will be in the
empty context.
Dynamic contexts can be explicitly disabled by setting ``dynamic_context`` to
``none``.
.. _context_reporting:
Context reporting
-----------------
The ``coverage report`` and ``coverage html`` commands both accept
``--contexts`` option, a comma-separated list of regular expressions. The
report will be limited to the contexts that match one of those patterns.
The ``coverage html`` command also has ``--show-contexts``. If set, the HTML
report will include an annotation on each covered line indicating the number of
contexts that executed the line. Clicking the annotation displays a list of
the contexts.
Raw data
--------
For more advanced reporting or analysis, the .coverage data file is a SQLite
database. See :ref:`dbschema` for details.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/contributing.rst 0000644 0001751 0001751 00000037005 15073731535 017065 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. Command samples here were made with a 100-column terminal.
.. _contributing:
===========================
Contributing to coverage.py
===========================
.. highlight:: console
I welcome contributions to coverage.py. Over the years, hundreds of people
have provided contributions of various sizes to add features, fix bugs, or just
help diagnose thorny issues. This page should have all the information you
need to make a contribution.
One source of history or ideas are the `bug reports`_ against coverage.py.
There you can find ideas for requested features, or the remains of rejected
ideas.
.. _bug reports: https://github.com/nedbat/coveragepy/issues
Before you begin
----------------
If you have an idea for coverage.py, run it by me before you begin writing
code. This way, I can get you going in the right direction, or point you to
previous work in the area. Things are not always as straightforward as they
seem, and having the benefit of lessons learned by those before you can save
you frustration.
We have a `#coverage channel in the Python Discord `_ that can be a
good place to explore ideas, get help, or help people with coverage.py.
`Join us `_!
.. _discord: https://discord.com/channels/267624335836053506/1253355750684753950
Getting the code
----------------
.. PYVERSIONS (mention of lowest version in the "create virtualenv" step).
The coverage.py code is hosted on a GitHub repository at
https://github.com/nedbat/coveragepy. To get a working environment, follow
these steps:
#. `Fork the repo`_ into your own GitHub account. The coverage.py code will
then be copied into a GitHub repository at
``https://github.com/GITHUB_USER/coveragepy`` where GITHUB_USER is your
GitHub username.
#. (Optional) Create a virtualenv to work in, and activate it. There
are a number of ways to do this. Use the method you are comfortable with.
Ideally, use Python 3.10 (the lowest version coverage.py supports).
#. Clone the repository::
$ git clone https://github.com/GITHUB_USER/coveragepy
$ cd coveragepy
#. Install the requirements with either of these commands::
$ make install
$ python3 -m pip install -r requirements/dev.pip
Note: You may need to upgrade pip to install the requirements.
Running the tests
-----------------
.. To get the test output:
# Use the lowest of the PYVERSIONS
# Resize terminal width to 95
% make sterile
.. with COVERAGE_ONE_CORE=
The tests are written mostly as standard unittest-style tests, and are run with
pytest running under `tox`_::
% python3 -m tox -e py39
py39: wheel-0.45.1-py3-none-any.whl already present in /Users/ned/Library/Application Support/virtualenv/wheel/3.9/embed/3/wheel.json
py39: pip-25.0.1-py3-none-any.whl already present in /Users/ned/Library/Application Support/virtualenv/wheel/3.9/embed/3/pip.json
py39: setuptools-78.1.0-py3-none-any.whl already present in /Users/ned/Library/Application Support/virtualenv/wheel/3.9/embed/3/setuptools.json
py39: install_deps> python -m pip install -U -r requirements/pip.pip -r requirements/pytest.pip -r requirements/light-threads.pip
.pkg: install_requires> python -I -m pip install setuptools
.pkg: _optional_hooks> python /usr/local/virtualenvs/coverage/lib/python3.9/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: get_requires_for_build_editable> python /usr/local/virtualenvs/coverage/lib/python3.9/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: build_editable> python /usr/local/virtualenvs/coverage/lib/python3.9/site-packages/pyproject_api/_backend.py True setuptools.build_meta
py39: install_package_deps> python -m pip install -U 'tomli; python_full_version <= "3.11.0a6"'
py39: install_package> python -m pip install -U --force-reinstall --no-deps .tox/.tmp/package/1/coverage-7.8.1a0.dev1-0.editable-cp39-cp39-macosx_15_0_arm64.whl
py39: commands[0]> python igor.py zip_mods
py39: commands[1]> python igor.py remove_extension
py39: commands[2]> python igor.py test_with_core pytrace
=== CPython 3.9.21 (gil) with Python tracer (.tox/py39/bin/python) ===
bringing up nodes...
....................................................................................... [ 5%]
..................................................................x................s... [ 11%]
......s...s.....s....s......s.s.s.s.................................................... [ 17%]
...........................................s..ss...ss.ss.ss............................ [ 23%]
....................................................................................... [ 29%]
....................................................................................... [ 35%]
....................................................................................... [ 41%]
................................................s...................................... [ 47%]
....................................................................................... [ 53%]
...................................................s..........s........................ [ 59%]
....................................................................................... [ 65%]
..........................ssss......................................................... [ 71%]
..s.....s.ss..........................ss...................s.s..sssssss.ssssss.sssss... [ 77%]
.........ss..........................s...s.s......s........s........................s.. [ 83%]
.............................s......................................................... [ 88%]
....................................................................................... [ 94%]
.............................................s.......................ss.... [100%]
1403 passed, 63 skipped, 1 xfailed in 15.05s
py39: commands[3]> python setup.py --quiet build_ext --inplace
py39: commands[4]> python -m pip install -q -e .
py39: commands[5]> python igor.py test_with_core ctrace
=== CPython 3.9.21 (gil) with C tracer (.tox/py39/bin/python) ===
bringing up nodes...
....................................................................................... [ 5%]
..........................................sx................................s.......... [ 11%]
..........ss........s....................................s............................. [ 17%]
..............................sss...................................................... [ 23%]
..............................................................s........................ [ 29%]
....................................................................................... [ 35%]
....................................................................................... [ 41%]
......................................................s................................ [ 47%]
.............................................s......................................... [ 53%]
.......s..................s............................................................ [ 59%]
....................................................................................s.. [ 65%]
.......................................................ss.......................s...... [ 71%]
....................................................s............................ss.... [ 77%]
..........................s...................s........................................ [ 83%]
....................................................................................... [ 88%]
............................s......s................................................... [ 94%]
.................................................................s......... [100%]
1440 passed, 26 skipped, 1 xfailed in 12.38s
py39: OK (40.04=setup[9.03]+cmd[0.17,0.09,15.40,0.13,2.47,12.77] seconds)
congratulations :) (40.61 seconds)
Tox runs the complete test suite a few times for each version of Python you
have installed. The first run uses the C implementation of the trace function,
the second uses the Python implementation. If `sys.monitoring`_ is available,
the suite will be run again with that core.
To limit tox to just a few versions of Python, use the ``-e`` switch::
$ python3 -m tox -e py38,py39
On the tox command line, options after ``--`` are passed to pytest. To run
just a few tests, you can use `pytest test selectors`_::
$ python3 -m tox -- tests/test_misc.py
$ python3 -m tox -- tests/test_misc.py::HasherTest
$ python3 -m tox -- tests/test_misc.py::HasherTest::test_string_hashing
.. with COVERAGE_ONE_CORE=1
These commands run the tests in one file, one class, and just one test,
respectively. The pytest ``-k`` option selects tests based on a word in their
name, which can be very convenient for ad-hoc test selection. Of course you
can combine tox and pytest options::
% python3 -m tox -q -e py310 -- -n 0 -vv -k hash
Skipping tests with Python tracer: Only one core: not running pytrace
=== CPython 3.10.16 (gil) with C tracer (.tox/py310/bin/python) ===
===================================== test session starts =====================================
platform darwin -- Python 3.10.16, pytest-8.3.5, pluggy-1.5.0 -- /Users/ned/coverage/trunk/.tox/py310/bin/python
cachedir: .tox/py310/.pytest_cache
hypothesis profile 'default' -> database=DirectoryBasedExampleDatabase(PosixPath('/Users/ned/coverage/trunk/.hypothesis/examples'))
rootdir: /Users/ned/coverage/trunk
configfile: pyproject.toml
plugins: flaky-3.8.1, hypothesis-6.128.1, xdist-3.6.1
collected 1467 items / 1457 deselected / 10 selected
run-last-failure: no previously failed tests, not deselecting items.
tests/test_data.py::CoverageDataTest::test_add_to_hash_with_lines PASSED [ 10%]
tests/test_data.py::CoverageDataTest::test_add_to_hash_with_arcs PASSED [ 20%]
tests/test_data.py::CoverageDataTest::test_add_to_lines_hash_with_missing_file PASSED [ 30%]
tests/test_data.py::CoverageDataTest::test_add_to_arcs_hash_with_missing_file PASSED [ 40%]
tests/test_execfile.py::RunPycFileTest::test_running_hashed_pyc PASSED [ 50%]
tests/test_misc.py::HasherTest::test_string_hashing PASSED [ 60%]
tests/test_misc.py::HasherTest::test_bytes_hashing PASSED [ 70%]
tests/test_misc.py::HasherTest::test_unicode_hashing PASSED [ 80%]
tests/test_misc.py::HasherTest::test_dict_hashing PASSED [ 90%]
tests/test_misc.py::HasherTest::test_dict_collision PASSED [100%]
============================= 10 passed, 1457 deselected in 3.13s =============================
py310: OK (16.62 seconds)
congratulations :) (16.97 seconds)
You can also affect the test runs with environment variables:
- ``COVERAGE_ONE_CORE=1`` will use only one tracing core for each Python
version. This isn't about CPU cores, it's about the central code that tracks
execution. This will use the preferred core for the Python version and
implementation being tested.
- ``COVERAGE_TEST_CORES=...`` defines the cores to run tests on. Three cores
are available, specify them as a comma-separated string:
- ``ctrace`` is a sys.settrace function implemented in C.
- ``pytrace`` is a sys.settrace function implemented in Python.
- ``sysmon`` is a `sys.monitoring`_ implementation.
- ``COVERAGE_AST_DUMP=1`` will dump the AST tree as it is being used during
code parsing.
There are other environment variables that affect tests. I use `set_env.py`_
as a simple terminal interface to see and set them.
Of course, run all the tests on every version of Python you have before
submitting a change.
Lint, etc
---------
I try to keep the coverage.py source as clean as possible. I use pylint to
alert me to possible problems::
$ make lint
The source is pylint-clean, even if it's because there are pragmas quieting
some warnings. Please try to keep it that way, but don't let pylint warnings
keep you from sending patches. I can clean them up.
Lines should be kept to a 100-character maximum length. I recommend an
`editorconfig.org`_ plugin for your editor of choice, which will also help with
indentation, line endings and so on. Source files are formatted with `ruff`_.
I use `pre-commit`_ to run checks and formatting when making commits, you
should also.
Other style questions are best answered by looking at the existing code.
Formatting of docstrings, comments, long lines, and so on, should match the
code that already exists.
Cog
---
Parts of the documentation and GitHub actions are kept up-to-date with `cog`_.
There are checks to make sure that files are correct and not being incorrectly
edited.
If a check fails, it will show you what command to run to update the files.
If you edit parts of a file that should be generated, you will see a message
like::
Output has been edited! Delete old checksum to unprotect.
Probably you should revert the edits and run the command to generate the
output. The top of the file you edited will have instructions.
.. _cog: https://cog.readthedocs.io
Continuous integration
----------------------
When you make a pull request, `GitHub actions`__ will run all of the tests and
quality checks on your changes. If any fail, either fix them or ask for help.
__ https://github.com/nedbat/coveragepy/actions
Dependencies
------------
Coverage.py has no direct runtime dependencies, and I would like to keep it
that way.
It has many development dependencies. These are specified generically in the
``requirements/*.in`` files. The .in files should have no versions specified
in them. The specific versions to use are pinned in ``requirements/*.pip``
files. These are created by running ``make upgrade``.
.. minimum of PYVERSIONS:
It's important to use Python 3.10 to run ``make upgrade`` so that the pinned
versions will work on all of the Python versions currently supported by
coverage.py.
If for some reason we need to constrain a version of a dependency, the
constraint should be specified in the ``requirements/pins.pip`` file, with a
detailed reason for the pin.
Coverage testing coverage.py
----------------------------
Coverage.py can measure itself, but it's complicated. The process has been
packaged up to make it easier::
$ make metacov metahtml
Then look at htmlcov/index.html. Note that due to the recursive nature of
coverage.py measuring itself, there are some parts of the code that will never
appear as covered, even though they are executed.
Contributing
------------
When you are ready to contribute a change, any way you can get it to me is
probably fine. A pull request on GitHub is great, but a simple diff or
patch works too.
All contributions are expected to include tests for new functionality and
fixes. If you need help writing tests, please ask.
.. _fork the repo: https://docs.github.com/en/get-started/quickstart/fork-a-repo
.. _editorconfig.org: http://editorconfig.org
.. _tox: https://tox.readthedocs.io/
.. _ruff: https://pypi.org/project/ruff/
.. _pre-commit: https://pre-commit.com/
.. _set_env.py: https://nedbatchelder.com/blog/201907/set_envpy.html
.. _pytest test selectors: https://doc.pytest.org/en/stable/usage.html#specifying-which-tests-to-run
.. _sys.monitoring: https://docs.python.org/3/library/sys.monitoring.html
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/dbschema.rst 0000644 0001751 0001751 00000007716 15073731535 016132 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is meant to be processed with cog to insert the latest database
schema into the docs. If it's out of date, the quality checks will fail.
Running "make prebuild" will bring it up to date.
.. _dbschema:
===========================
Coverage.py database schema
===========================
.. versionadded:: 5.0
Coverage.py stores data in a SQLite database, by default called ``.coverage``.
For most needs, the :class:`.CoverageData` API will be sufficient, and should
be preferred to accessing the database directly. Only advanced uses will need
to use the database.
The schema can change without changing the major version of coverage.py, so be
careful when accessing the database directly. The ``coverage_schema`` table
has the schema number of the database. The schema described here corresponds
to:
.. [[[cog
from coverage.sqldata import SCHEMA_VERSION
print(".. code::")
print()
print(f" SCHEMA_VERSION = {SCHEMA_VERSION}")
print()
.. ]]]
.. code::
SCHEMA_VERSION = 7
.. [[[end]]] (sum: ladTQN8zI3)
You can use SQLite tools such as the :mod:`sqlite3 ` module in
the Python standard library to access the data. Some data is stored in a
packed format that will need custom functions to access. See
:func:`.register_sqlite_functions`.
Database schema
---------------
This is the database schema:
.. [[[cog
import textwrap
from coverage.sqldata import SCHEMA
print(".. code-block:: sql")
print()
print(textwrap.indent(SCHEMA, " "))
.. ]]]
.. code-block:: sql
CREATE TABLE coverage_schema (
-- One row, to record the version of the schema in this db.
version integer
);
CREATE TABLE meta (
-- Key-value pairs, to record metadata about the data
key text,
value text,
unique (key)
-- Possible keys:
-- 'has_arcs' boolean -- Is this data recording branches?
-- 'sys_argv' text -- The coverage command line that recorded the data.
-- 'version' text -- The version of coverage.py that made the file.
-- 'when' text -- Datetime when the file was created.
);
CREATE TABLE file (
-- A row per file measured.
id integer primary key,
path text,
unique (path)
);
CREATE TABLE context (
-- A row per context measured.
id integer primary key,
context text,
unique (context)
);
CREATE TABLE line_bits (
-- If recording lines, a row per context per file executed.
-- All of the line numbers for that file/context are in one numbits.
file_id integer, -- foreign key to `file`.
context_id integer, -- foreign key to `context`.
numbits blob, -- see the numbits functions in coverage.numbits
foreign key (file_id) references file (id),
foreign key (context_id) references context (id),
unique (file_id, context_id)
);
CREATE TABLE arc (
-- If recording branches, a row per context per from/to line transition executed.
file_id integer, -- foreign key to `file`.
context_id integer, -- foreign key to `context`.
fromno integer, -- line number jumped from.
tono integer, -- line number jumped to.
foreign key (file_id) references file (id),
foreign key (context_id) references context (id),
unique (file_id, context_id, fromno, tono)
);
CREATE TABLE tracer (
-- A row per file indicating the tracer used for that file.
file_id integer primary key,
tracer text,
foreign key (file_id) references file (id)
);
.. [[[end]]] (sum: agTRSwfwj4)
.. _numbits:
Numbits
-------
.. automodule:: coverage.numbits
:members:
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/dict.txt 0000644 0001751 0001751 00000004607 15073731535 015312 0 ustar 00runner runner API
BOM
BTW
CPython
CTracer
Cobertura
Consolas
Cython
DOCTYPE
DOM
HTML
Jinja
Mako
OK
PYTHONPATH
TODO
Tidelift
URL
UTF
XML
activestate
apache
api
args
argv
ascii
async
basename
basenames
bitbucket
bom
boolean
booleans
btw
builtin
builtins
bytecode
bytecodes
bytestring
callable
callables
canonicalize
canonicalized
canonicalizes
chdir'd
clickable
cmdline
codecs
colorsys
combinable
conditionalizing
config
configparser
configurability
configurability's
configurer
configurers
cov
coveragepy
coveragerc
covhtml
css
dataio
datetime
deallocating
debounce
decodable
dedent
defaultdict
deserialize
deserialized
dict
dict's
dicts
dirname
django
docstring
docstrings
doctest
doctests
encodable
encodings
endfor
endif
eventlet
exe
exec'd
exec'ing
execfile
executability
executable's
execv
expr
extensibility
favicon
filename
filenames
filepath
filereporter
fname
fnmatch
fooey
formfeed
fpath
fullcoverage
gauge
getattr
gevent
gevent's
github
gitignore
globals
greenlet
hintedness
hotkey
hotkeys
html
htmlcov
http
https
importlib
installable
instancemethod
int
ints
invariants
iterable
iterables
jQuery
jquery
json
jython
kwargs
lcov
localStorage
manylinux
matcher
matchers
merchantability
metadata
meth
mischaracterize
mischaracterized
mixin
modulename
monkeypatch
monkeypatching
monospaced
morf
morfs
multi
multiproc
mumbo
mycode
mypy
namespace
namespaces
nano
nbsp
ned
nedbat
nedbatchelder
newb
nocover
nosetests
nullary
num
numbits
numpy
ok
opcode
opcodes
optparse
os
outfile
overridable
parallelizing
parsable
parsers
pathlib
pathnames
plugin
plugins
pragma
pragma'd
pragmas
pre
premain
prepended
prepending
programmability
programmatically
py
py's
pyc
pyenv
pyexpat
pylib
pylint
pyproject
pypy
pytest
pythonpath
pyw
rcfile
readme
readthedocs
realpath
recordable
refactored
refactoring
refactorings
regex
regexes
reimplemented
renderer
rootname
runnable
runtime
scrollbar
septatrix
serializable
settrace
setuptools
sigterm
sitecustomize
sortable
src
stackoverflow
stderr
stdlib
stdout
str
subclasses
subdirectory
subprocess
subprocesses
symlink
symlinks
syntaxes
sys
templating
templite
testability
todo
tokenization
tokenize
tokenized
tokenizer
tokenizes
tokenizing
toml
tomllib
tox
traceback
tracebacks
tuple
tuples
txt
ubuntu
undecodable
unexecutable
unicode
uninstall
unittest
unparsable
unrunnable
unsubscriptable
untokenizable
usecache
username
utf
vendored
versionadded
virtualenv
wikipedia
wildcard
wildcards
www
xdist
xml
xrange
xyzzy
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/excluding.rst 0000644 0001751 0001751 00000027232 15073731535 016341 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to create the tabbed multi-syntax
configuration examples. If those are wrong, the quality checks will fail.
Running "make prebuild" checks them and produces the output.
.. [[[cog
from cog_helpers import show_configs
.. ]]]
.. [[[end]]] (sum: 1B2M2Y8Asg)
.. _excluding:
===============================
Excluding code from coverage.py
===============================
.. highlight:: python
You may have code in your project that you know won't be executed, and you want
to tell coverage.py to ignore it. For example, you may have debugging-only
code that won't be executed during your unit tests. You can tell coverage.py to
exclude this code during reporting so that it doesn't clutter your reports with
noise about code that you don't need to hear about.
Coverage.py will look for comments marking clauses for exclusion. In this
code, the "if debug" clause is excluded from reporting::
a = my_function1()
if debug: # pragma: no cover
msg = "blah blah"
log_message(msg, a)
b = my_function2()
By default, any line with a comment of ``pragma: no cover`` is excluded. If
that line introduces a clause, for example, an ``if`` clause, or a function or
class definition, then the entire clause is also excluded. Here the
``__repr__`` function is not reported as missing::
class MyObject(object):
def __init__(self):
blah1()
blah2()
def __repr__(self): # pragma: no cover
return ""
Excluded code is executed as usual, and its execution is recorded in the
coverage data as usual. When producing reports though, coverage.py excludes it
from the list of missing code.
Branch coverage
---------------
When measuring :ref:`branch coverage `, a conditional will not be
counted as a branch if one of its choices is excluded::
def only_one_choice(x):
if x:
blah1()
blah2()
else: # pragma: no cover
# x is always true.
blah3()
Because the ``else`` clause is excluded, the ``if`` only has one possible next
line, so it isn't considered a branch at all.
Default exclusions
------------------
Coverage.py has a set of built-in exclusion patterns. For line coverage, these
lines are automatically excluded:
- Any line with a comment like ``# pragma: no cover``. Other slight
differences in spacing and letter case are also recognized.
- Any line with only ``...`` in the code, for excluding placeholder function
bodies.
For branch coverage, these kinds of branches are automatically excluded:
- A branch with a comment like ``# pragma: no branch``, including differences
in spacing and letter case.
- Some branches that are known at compile time: ``if True:``, ``while True:``,
and so on.
- A branch just for type checkers: ``if TYPE_CHECKING:``.
.. versionadded:: 7.10.0 the ``...`` and ``TYPE_CHECKING`` defaults.
Advanced exclusion
------------------
Coverage.py identifies exclusions by matching source code against a list of
regular expressions. Using :ref:`configuration files ` or the coverage
:ref:`API `, you can add to that list. This is useful if you have
often-used constructs to exclude that can be matched with a regex. You can
exclude them all at once in your configuration without littering your code with
exclusion pragmas.
Before coverage.py 7.6.0, the regexes were matched against single lines of your
source code. Now they can be multi-line regexes that find matches across
lines. See :ref:`multi_line_exclude`.
If a matched line introduces a block, the entire block is excluded from
reporting. Matching a ``def`` line or decorator line will exclude an entire
function.
.. highlight:: ini
For example, you might decide that __repr__ functions are usually only used in
debugging code, and are uninteresting to test themselves. You could exclude
all of them by adding a regex to the exclusion list:
.. [[[cog
show_configs(
ini=r"""
[report]
exclude_also =
def __repr__
""",
toml=r"""
[tool.coverage.report]
exclude_also = [
"def __repr__",
]
""",
)
.. ]]]
.. tabs::
.. code-tab:: ini
:caption: .coveragerc
[report]
exclude_also =
def __repr__
.. code-tab:: toml
:caption: pyproject.toml
[tool.coverage.report]
exclude_also = [
"def __repr__",
]
.. code-tab:: ini
:caption: setup.cfg or tox.ini
[coverage:report]
exclude_also =
def __repr__
.. [[[end]]] (sum: 8+cOvxKPvv)
For example, here's a list of exclusions I've used:
.. [[[cog
show_configs(
ini=r"""
[report]
exclude_also =
def __repr__
if self.debug:
if settings.DEBUG
raise AssertionError
raise NotImplementedError
if 0:
if __name__ == .__main__.:
if TYPE_CHECKING:
class .*\bProtocol\):
@(abc\.)?abstractmethod
""",
toml=r"""
[tool.coverage.report]
exclude_also = [
'def __repr__',
'if self.debug:',
'if settings.DEBUG',
'raise AssertionError',
'raise NotImplementedError',
'if 0:',
'if __name__ == .__main__.:',
'if TYPE_CHECKING:',
'class .*\bProtocol\):',
'@(abc\.)?abstractmethod',
]
""",
)
.. ]]]
.. tabs::
.. code-tab:: ini
:caption: .coveragerc
[report]
exclude_also =
def __repr__
if self.debug:
if settings.DEBUG
raise AssertionError
raise NotImplementedError
if 0:
if __name__ == .__main__.:
if TYPE_CHECKING:
class .*\bProtocol\):
@(abc\.)?abstractmethod
.. code-tab:: toml
:caption: pyproject.toml
[tool.coverage.report]
exclude_also = [
'def __repr__',
'if self.debug:',
'if settings.DEBUG',
'raise AssertionError',
'raise NotImplementedError',
'if 0:',
'if __name__ == .__main__.:',
'if TYPE_CHECKING:',
'class .*\bProtocol\):',
'@(abc\.)?abstractmethod',
]
.. code-tab:: ini
:caption: setup.cfg or tox.ini
[coverage:report]
exclude_also =
def __repr__
if self.debug:
if settings.DEBUG
raise AssertionError
raise NotImplementedError
if 0:
if __name__ == .__main__.:
if TYPE_CHECKING:
class .*\bProtocol\):
@(abc\.)?abstractmethod
.. [[[end]]] (sum: ZQsgnt0nES)
The :ref:`config_report_exclude_also` option adds regexes to the built-in
default list so that you can add your own exclusions. The older
:ref:`config_report_exclude_lines` option completely overwrites the list of
regexes.
The regexes only have to match part of a line. Be careful not to over-match.
The regex ``...`` will match any line with more than three characters in it,
which is certainly not what you want to exclude.
.. _multi_line_exclude:
Multi-line exclusion regexes
----------------------------
.. versionadded:: 7.6.0
Exclusion regexes can match multi-line regions. All of the lines in a matched
region will be excluded. If part of the region introduces a block, the entire
block is excluded even if part of it is outside the matched region.
When writing regexes to match multiple lines, remember that ``"."`` won't match
a newline character, but ``"\n"`` or ``"(?s:.)"`` will. The regexes in these
settings are combined, so you cannot use global flags like ``(?s)`` in
your regexes. Use the scoped flag form instead: ``(?s:...)``
Here are some examples:
.. [[[cog
show_configs(
ini=r"""
[report]
exclude_also =
; 1. Exclude an except clause of a specific form:
except ValueError:\n\s*assume\(False\)
; 2. Comments to turn coverage on and off:
no cover: start(?s:.)*?no cover: stop
; 3. A pragma comment that excludes an entire file:
\A(?s:.*# pragma: exclude file.*)\Z
""",
toml=r"""
[tool.coverage.report]
exclude_also = [
# 1. Exclude an except clause of a specific form:
'except ValueError:\n\s*assume\(False\)',
# 2. Comments to turn coverage on and off:
'no cover: start(?s:.)*?no cover: stop',
# 3. A pragma comment that excludes an entire file:
'\A(?s:.*# pragma: exclude file.*)\Z',
]
""",
)
.. ]]]
.. tabs::
.. code-tab:: ini
:caption: .coveragerc
[report]
exclude_also =
; 1. Exclude an except clause of a specific form:
except ValueError:\n\s*assume\(False\)
; 2. Comments to turn coverage on and off:
no cover: start(?s:.)*?no cover: stop
; 3. A pragma comment that excludes an entire file:
\A(?s:.*# pragma: exclude file.*)\Z
.. code-tab:: toml
:caption: pyproject.toml
[tool.coverage.report]
exclude_also = [
# 1. Exclude an except clause of a specific form:
'except ValueError:\n\s*assume\(False\)',
# 2. Comments to turn coverage on and off:
'no cover: start(?s:.)*?no cover: stop',
# 3. A pragma comment that excludes an entire file:
'\A(?s:.*# pragma: exclude file.*)\Z',
]
.. code-tab:: ini
:caption: setup.cfg or tox.ini
[coverage:report]
exclude_also =
; 1. Exclude an except clause of a specific form:
except ValueError:\n\s*assume\(False\)
; 2. Comments to turn coverage on and off:
no cover: start(?s:.)*?no cover: stop
; 3. A pragma comment that excludes an entire file:
\A(?s:.*# pragma: exclude file.*)\Z
.. [[[end]]] (sum: xG6Bmtmh06)
The first regex matches a specific except line followed by a specific function
call. Both lines must be present for the exclusion to take effect. Note that
the regex uses ``"\n\s*"`` to match the newline and the indentation of the
second line. Without these, the regex won't match.
The second regex creates a pair of comments that can be used to exclude
statements between them. All lines between ``# no cover: start`` and ``# no
cover: stop`` will be excluded. The regex doesn't start with ``#`` because
that's a comment in a .coveragerc file. Be careful with wildcards: we've used
the non-greedy ``*?`` to match the fewest possible characters between the
comments. If you used the greedy ``*`` instead, the star would match as many
as possible, and you could accidentally exclude large swaths of code.
The third regex matches the entire text of a file containing the comment ``#
pragma: exclude file``. This lets you exclude files from coverage measurement
with an internal comment instead of naming them in a settings file. This regex
uses the ``"(?s:...)"`` regex flag to let a dot match any character including a
newline.
Excluding source files
----------------------
See :ref:`source` for ways to limit what files coverage.py measures or reports
on.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/faq.rst 0000644 0001751 0001751 00000017201 15073731535 015121 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _faq:
==================
FAQ and other help
==================
Frequently asked questions
--------------------------
Q: Why are some of my files not measured?
.........................................
Coverage.py has a number of mechanisms for deciding which files to measure and
which to skip. If your files aren't being measured, use the ``--debug=trace``
:ref:`option `, also settable as ``[run] debug=trace`` in the
:ref:`settings file `, or as ``COVERAGE_DEBUG=trace`` in an
environment variable.
This will write a line for each file considered, indicating whether it is
traced or not, and if not, why not. Be careful though: the output might be
swallowed by your test runner. If so, a ``COVERAGE_DEBUG_FILE=/tmp/cov.out``
environment variable can direct the output to a file instead to ensure you see
everything.
Q: Why do unexecutable lines show up as executed?
.................................................
Usually this is because you've updated your code and run coverage.py on it
again without erasing the old data. Coverage.py records line numbers executed,
so the old data may have recorded a line number which has since moved, causing
coverage.py to claim a line has been executed which cannot be.
If old data is persisting, you can use an explicit ``coverage erase`` command
to clean out the old data.
Q: Why are my function definitions marked as run when I haven't tested them?
............................................................................
The ``def`` and ``class`` lines in your Python file are executed when the file
is imported. Those are the lines that define your functions and classes. They
run even if you never call the functions. It's the body of the functions that
will be marked as not executed if you don't test them, not the ``def`` lines.
This can mean that your code has a moderate coverage total even if no tests
have been written or run. This might seem surprising, but it is accurate: the
``def`` lines have actually been run.
Q: Why do the bodies of functions show as executed, but the def lines do not?
.............................................................................
If this happens, it's because coverage.py has started after the functions are
defined. The definition lines are executed without coverage measurement, then
coverage.py is started, then the function is called. This means the body is
measured, but the definition of the function itself is not.
The same thing can happen with the bodies of classes.
To fix this, start coverage.py earlier. If you use the :ref:`command line
` to run your program with coverage.py, then your entire program will be
monitored. If you are using the :ref:`API `, you need to call
coverage.start() before importing the modules that define your functions.
Q: My decorator lines are marked as covered, but the "def" line is not. Why?
.............................................................................
Different versions of Python report execution on different lines. Coverage.py
adapts its behavior to the version of Python being used. In Python 3.7 and
earlier, a decorated function definition only reported the decorator as
executed. In Python 3.8 and later, both the decorator and the "def" are
reported. If you collect execution data on Python 3.7, and then run coverage
reports on Python 3.8, there will be a discrepancy.
Q: Can I find out which tests ran which lines?
..............................................
Yes! Coverage.py has a feature called :ref:`dynamic_contexts` which can collect
this information. Add this to your .coveragerc file:
.. code-block:: ini
[run]
dynamic_context = test_function
and then use the ``--contexts`` option when generating an HTML report.
Q: How is the total percentage calculated?
..........................................
For line coverage, coverage.py counts the total number of possible executions.
This is the number of executable statements minus the number of excluded
statements. It then counts the number of those possibilities that were
actually executed. The total percentage is the actual executions divided by
the possible executions.
As an example, a coverage report with 1514 statements and 901 missed
statements would calculate a total percentage of (1514-901)/1514, or 40.49%.
:ref:`Branch coverage ` extends the calculation to include the total
number of possible branch exits, and the number of those taken. In this case
the specific numbers shown in the text or HTML reports don't calculate out to
the percentage shown, because the number of missing branch exits isn't reported
explicitly. A branch line that wasn't executed at all is counted once as a
missing statement in the report, instead of as two missing branches. Reports
show the number of partial branches, which is the lines that were executed but
did not execute all of their exits.
The :ref:`JSON report ` includes more data that can be used to
re-calculate the total percentage. Individual files have a ``summary`` key,
and the report as a whole has a ``totals`` key that include items like these:
.. code-block:: json
{
"covered_branches": 5,
"covered_lines": 9,
"excluded_lines": 0,
"missing_branches": 11,
"missing_lines": 105,
"num_branches": 16,
"num_partial_branches": 5,
"num_statements": 114,
"percent_covered": 10.76923076923077,
"percent_covered_display": "11"
}
The total percentage is calculated as::
percent_covered =
(covered_lines + covered_branches) /
(num_statements + num_branches)
Q: Coverage.py is much slower than I remember, what's going on?
...............................................................
Make sure you are using the C trace function. Coverage.py provides two
implementations of the trace function. The C implementation runs much faster.
To see what you are running, use ``coverage debug sys``. The output contains
details of the environment, including a line that says either
``CTracer: available`` or ``CTracer: unavailable``. If it says unavailable,
then you are using the slow Python implementation.
Try re-installing coverage.py to see what happened and if you get the CTracer
as you should.
Q: Isn't coverage testing the best thing ever?
..............................................
It's good, but `it isn't perfect`__.
__ https://nedbatchelder.com/blog/200710/flaws_in_coverage_measurement.html
Q: Where can I get more help with coverage.py?
..............................................
You can discuss coverage.py or get help using it on the `Python discussion
forums`_ or in the `Python Discord`_. If you ping me (``@nedbat``), there's a
higher chance I'll see the post.
.. _Python discussion forums: https://discuss.python.org/
.. _Python Discord: https://discord.com/channels/267624335836053506/1253355750684753950
Bug reports are gladly accepted at the `GitHub issue tracker`_.
.. _GitHub issue tracker: https://github.com/nedbat/coveragepy/issues
`I can be reached`__ in a number of ways. I'm happy to answer questions about
using coverage.py.
__ https://nedbatchelder.com/site/aboutned.html
History
-------
Coverage.py was originally written by `Gareth Rees`_.
Since 2004, `Ned Batchelder`_ has extended and maintained it with the help of
`many others`_. The :ref:`change history ` has all the details.
.. _Gareth Rees: http://garethrees.org/
.. _Ned Batchelder: https://nedbatchelder.com
.. _many others: https://github.com/nedbat/coveragepy/blob/master/CONTRIBUTORS.txt
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/howitworks.rst 0000644 0001751 0001751 00000011315 15073731535 016572 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. _howitworks:
=====================
How coverage.py works
=====================
For advanced use of coverage.py, or just because you are curious, it helps to
understand what's happening behind the scenes.
Coverage.py works in three phases:
* **Execution**: Coverage.py runs your code, and monitors it to see what lines
were executed.
* **Analysis**: Coverage.py examines your code to determine what lines could
have run.
* **Reporting**: Coverage.py combines the results of execution and analysis to
produce a coverage number and an indication of missing execution.
The execution phase is handled by the ``coverage run`` command. The analysis
and reporting phases are handled by the reporting commands like ``coverage
report`` or ``coverage html``.
As a short-hand, I say that coverage.py measures what lines were executed. But
it collects more information than that. It can measure what branches were
taken, and if you have contexts enabled, for each line or branch, it will also
measure what contexts they were executed in.
Let's look at each phase in more detail.
Execution
---------
At the heart of the execution phase is a trace function. This is a function
that the Python interpreter invokes for each line executed in a program.
Coverage.py implements a trace function that records each file and line number
as it is executed.
For more details of trace functions, see the Python docs for `sys.settrace`_,
or if you are really brave, `How C trace functions really work`_.
Executing a function for every line in your program can make execution very
slow. Coverage.py's trace function is implemented in C to reduce that
overhead. It also takes care to not trace code that you aren't interested in.
When measuring branch coverage, the same trace function is used, but instead of
recording line numbers, coverage.py records pairs of line numbers. Each
invocation of the trace function remembers the line number, then the next
invocation records the pair `(prev, this)` to indicate that execution
transitioned from the previous line to this line. Internally, these are called
arcs.
As the data is being collected, coverage.py writes the data to a file, usually
named ``.coverage``. This is a :ref:`SQLite database ` containing
all of the measured data.
.. _sys.settrace: https://docs.python.org/3/library/sys.html#sys.settrace
.. _How C trace functions really work: https://nedbatchelder.com/text/trace-function.html
Plugins
.......
Of course coverage.py mostly measures execution of Python files. But it can
also be used to analyze other kinds of execution. :ref:`File tracer plugins
` provide support for non-Python files. For example,
Django HTML templates result in Python code being executed somewhere, but as a
developer, you want that execution mapped back to your .html template file.
During execution, each new Python file encountered is provided to the plugins
to consider. A plugin can claim the file and then convert the runtime Python
execution into source-level data to be recorded.
Dynamic contexts
................
When using :ref:`dynamic contexts `, there is a current
dynamic context that changes over the course of execution. It starts as empty.
While it is empty, every time a new function is entered, a check is made to see
if the dynamic context should change. While a non-empty dynamic context is
current, the check is skipped until the function that started the context
returns.
Analysis
--------
After your program has been executed and the line numbers recorded, coverage.py
needs to determine what lines could have been executed. Luckily, compiled
Python files (.pyc files) have a table of line numbers in them. Coverage.py
reads this table to get the set of executable lines, with a little more source
analysis to leave out things like docstrings.
The data file is read to get the set of lines that were executed. The
difference between the executable lines and the executed lines are the lines
that were not executed.
The same principle applies for branch measurement, though the process for
determining possible branches is more involved. Coverage.py uses the abstract
syntax tree of the Python source file to determine the set of possible
branches.
Reporting
---------
Once we have the set of executed lines and missing lines, reporting is a
matter of formatting that information in a useful way. Each reporting method
(text, HTML, JSON, annotated source, XML) has a different output format, but
the process is the same: write out the information in the particular format,
possibly including the source code itself.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1760539485.0
coverage-7.11.0/doc/index.rst 0000644 0001751 0001751 00000017545 15073731535 015474 0 ustar 00runner runner .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
===========
Coverage.py
===========
Coverage.py is a tool for measuring code coverage of Python programs. It
monitors your program, noting which parts of the code have been executed, then
analyzes the source to identify code that could have been executed but was not.
Coverage measurement is typically used to gauge the effectiveness of tests. It
can show which parts of your code are being exercised by tests, and which are
not.
The latest version is coverage.py |release|, released |release_date|. It is
supported on:
.. PYVERSIONS
* Python 3.10 through 3.15 alpha, including free-threading.
* PyPy3 versions 3.10 and 3.11.
.. ifconfig:: prerelease
**This is a pre-release build. The usual warnings about possible bugs
apply.** The latest stable version is coverage.py 6.5.0, `described here`_.
.. _described here: http://coverage.readthedocs.io/
For Enterprise
--------------
.. image:: media/Tidelift_Logos_RGB_Tidelift_Shorthand_On-White.png
:width: 75
:alt: Tidelift
:align: left
:class: tideliftlogo
:target: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=readme
`Available as part of the Tidelift Subscription. `_ |br|
Coverage and thousands of other packages are working with
Tidelift to deliver one enterprise subscription that covers all of the open
source you use. If you want the flexibility of open source and the confidence
of commercial-grade software, this is for you. `Learn more. `_
.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-coverage?utm_source=pypi-coverage&utm_medium=referral&utm_campaign=docs
Quick start
-----------
Getting started is easy:
#. Install coverage.py::
$ python3 -m pip install coverage
For more details, see :ref:`install`.
#. Use ``coverage run`` to run your test suite and gather data. However you
normally run your test suite, you can use your test runner under coverage.
.. tip::
If your test runner command starts with "python", replace the initial
"python" with "coverage run".
``python something.py`` becomes ``coverage run something.py``
``python -m amodule`` becomes ``coverage run -m amodule``
Other instructions for specific test runners:
.. tabs::
.. tab:: pytest
If you usually use::
$ pytest arg1 arg2 arg3
then you can run your tests under coverage with::
$ coverage run -m pytest arg1 arg2 arg3
Many people choose to use the `pytest-cov`_ plugin, but for most
purposes, it is unnecessary.
.. tab:: unittest
Change your python command name to "coverage run", so this::
$ python3 -m unittest discover
becomes::
$ coverage run -m unittest discover
.. tab:: nosetest
.. note:: Nose has been `unmaintained since at least 2015 `_.
*You should seriously consider using a different test runner.*
Change this::
$ nosetests arg1 arg2
to::
$ coverage run -m nose arg1 arg2
Coverage doesn't distinguish between tests and the code being tested.
We `recommend that you include your tests in coverage measurement `_.
To limit coverage measurement to code in the current directory, and also
find files that weren't executed at all, add the ``--source=.`` argument to
your coverage command line. You can also :ref:`specify source files to
measure ` or :ref:`exclude code from measurement