Welcome to README Coverage Badger
👋
Generates a coverage badge using coverage.py and the shields.io service. Your README file is then updated with the generated badge.
Source Code: github.com/engineervix/readme-coverage-badger
Contents generated with DocToc
- Why this project?
- Features
- Installation
- Usage
-
💻 Development - Author
-
🤝 Contributing - Show your support
-
✅ TODO -
📝 License
Why this project?
There are so many excellent coverage badge generation tools out there, why do we need another one? Well, at the time of writing this package (circa early 2021), all the existing tools (for example, coverage-badge) I had come across ended at generating SVG/PNG files/strings/Base64 images. What you do with this remains entirely up to you.
Now, it is often much easier to simply use online services such as codecov.io and coveralls.io. These services are free for open source projects, but require a monthly subscription for private repos. Many times, we work on private repos, and we wanna be able to automatically have coverage badges in our READMEs. What if you are unable to pay such subscription fees, or maybe you don't want to use a SaaS? Your solution becomes to generate your own badge!
This is where this project comes in. It automatically generates your project's coverage badge using the shields.io service, and then updates your README accordingly, in just one command! That's all it does, resonating with the Unix philosophy of doing one thing and doing it well. The main idea for this came from istanbul-badges-readme, which does exactly the same thing for JavaScript projects. You will see that these two projects have quite a lot in common.
After using istanbul-badges-readme, I searched for a python alternative but couldn't find anything suitable. The closest I found was coverage-badge, and if you look at this project's code, you will see a lot of similarities with coverage-badge!
If what you're looking for is a powerful, general purpose badge generation tool for your projects, then you should probably check out projects like anybadge and genbadge.
Features
- automatically generates your project's coverage badge using the shields.io service, and then updates your project's README with the newly generated badge
- simple CLI tool (
readme-cov) with helpful messages - tested on python 3.6 to 3.9 with coverage ≥ 84%
- free software: BSD-3-Clause license
- generates different colours depending on the coverage percentage. Optionally generate plain colour (green) regardless of percentage
- minimal external dependencies – this tool only has 2 external dependencies; Coverage.py (obviously!) and colorama (for cross-platform coloured terminal output)
The table below shows the coverage thresholds, associated colours and examples of generated badges:
| Coverage | Colour | Example |
|---|---|---|
| 0 ≤ coverage < 40 | red |  |
| 40 ≤ coverage < 60 | orange |  |
| 60 ≤ coverage < 75 | yellow |  |
| 75 ≤ coverage < 90 | yellowgreen |  |
| 90 ≤ coverage < 95 | green |  |
| 95 ≤ coverage ≤ 100 | brightgreen |  |
Installation
pip install readme-coverage-badger
Usage
Note: Before using the tool, ensure that you insert a string of the form ![Code Coverage]() or  in your project's README.
readme-cov [-h] [-v] [-p]
optional arguments:
-h, --help show the help message and exit
-v, --version show program's version number and exit
-p, --plain Plain colour mode. Standard green badge.
The tool operates on the basis of the following assumptions:
- you have a README.md or README file at the root of your project
- your README file is in markdown format. I know, some Pythonistas prefer restructuredtext! Sadly, this isn't supported (yet)
- Somewhere in your your README is a string in the form:
![Code Coverage]()or. This is what gets updated in-place (usingre.sub()) when the script runs. - the script is called from the root of your project repo, which has coverage.py already configured, and the coverage already updated (you have already run your tests prior to running the script)
- If the coverage badge in your README file is already up to date, your README file won't be updated, you will only be notified
💻
Development
First things first
- ensure that you have Python 3.6+ on your machine, and that you are able to configure python virtual environments.
- ensure that you have git setup on your machine.
Getting Started
First, fork this repository, then fire up your command prompt and ...
- Clone the forked repository
- Navigate to the cloned project directory:
cd readme_coverage_badger - activate your python virtual environment and
pip install --upgrade pip - Install dependencies:
pip install -r requirements_dev.txt - Setup pre-commit by running
pre-commit installfollowed bypre-commit install --hook-type commit-msg. Optionally runpre-commit run --all-filesto make sure your pre-commit setup is okay.
At this stage, hopefully everything should be working fine, and you should be able to start hacking on the project.
You can run the application via invoke run or
python readme_coverage_badger/__main__.py
Tests
Simply run pytest or invoke test to run tests in your virtual environment.
Test other Python versions by running tox.
Code Formatting
- Run
invoke lintto runflake8,black,isortandmypyon the code. - If you get any errors from
blackand/orisort, runinvoke lint --fixorinvoke lint -fso that black and isort can format your files. Alternatively, just runpre-commit. You can take a look at .pre-commit-config.yaml.
Author
- Blog: https://importthis.tech
- Twitter:
- Github: @engineervix
🤝
Contributing
Contributions, issues and feature requests are most welcome! A good place to start is by helping out with the unchecked items in the TODO section of this README!
Feel free to check the issues page and take a look at the contributing guide before you get started. In addition, please note the following:
- if you're making code contributions, please try and write some tests to accompany your code, and ensure that the tests pass. Also, were necessary, update the docs so that they reflect your changes.
- commit your changes via
cz commit. Follow the prompts. When you're done,pre-commitwill be invoked to ensure that your contributions and commits follow defined conventions. Seepre-commit-config.yamlfor more details. - your commit messages should follow the conventions described here. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like
git mergeandgit revert. Once you are done, please create a pull request.
Show your support
Please give a
✅
TODO
core
- Cater for not only markdown but also restructuredtext, and automatically detect if a file's syntax is markdown or restructuredtext if no extension given
- Provide option to generate badge in HTML format
- Provide option to generate to
stdoutand skip substitution in a README file. This could be useful if you're using the tool in a script and you just want the result so that you can use it elsewhere. - Allow for flexibility in choosing whatever colours one wants
- Allow for specifying Alt Text on the badge URL, for example
![Alt Text]()or - Make the codebase fully typed
- Improve the Tests by parametrizing fixtures and test functions
- improve CI/CD to cater for GNU/Linux, Mac OS X and Windows
- Create pre-commit hook
docs
- Add a screenshot / demo in this README
- Create standalone documentation for hosting either on Github Pages or readthedocs. This README is already detailed enough to serve as documentation!
other
- It would be fun if we had some kind of a badger logo!
📝
License
Copyright © 2021 Victor Miti.
This project is licensed under the terms of the BSD-3-Clause license.
This README was generated with
1 Oct 21, 2021
1 Jan 17, 2022
46 Sep 01, 2022
19 May 21, 2022
3 Sep 13, 2021
2 Jul 24, 2022
4 May 05, 2022
1 Nov 25, 2021
1 Nov 14, 2021
26 Dec 11, 2022
5 Jun 17, 2022
2 Jan 04, 2023
3 Sep 30, 2021
2 Feb 21, 2022
384 Jan 05, 2023
2 Oct 18, 2021
1 Nov 14, 2022
1 Jul 04, 2022
12 Nov 12, 2022
1 Oct 29, 2021