https://github.com/pkgcore/pkgcheck
pkgcore-based QA utility for ebuild repos
https://github.com/pkgcore/pkgcheck
ebuilds gentoo python qa
Last synced: 7 months ago
JSON representation
pkgcore-based QA utility for ebuild repos
- Host: GitHub
- URL: https://github.com/pkgcore/pkgcheck
- Owner: pkgcore
- License: bsd-3-clause
- Created: 2013-10-09T04:17:55.000Z (about 12 years ago)
- Default Branch: master
- Last Pushed: 2025-03-01T19:15:19.000Z (7 months ago)
- Last Synced: 2025-03-01T20:26:35.277Z (7 months ago)
- Topics: ebuilds, gentoo, python, qa
- Language: Python
- Homepage: https://pkgcore.github.io/pkgcheck
- Size: 7.3 MB
- Stars: 35
- Watchers: 5
- Forks: 30
- Open Issues: 134
-
Metadata Files:
- Readme: README.rst
- Changelog: NEWS.rst
- License: LICENSE
Awesome Lists containing this project
README
|pypi| |test| |coverage|
========
pkgcheck
========
Dependencies
============
pkgcheck is developed alongside pkgcore_ and snakeoil_. Running pkgcheck from
git will often require both pkgcore and snakeoil from git as well.
For releases, see the required runtime dependencies_.
There are also several optional runtime dependencies that add or extend check
support in various ways if found on the host system including the following:
- git_: supports historical queries for git-based repos and commit-related checks
- requests_: supports various network-related checks
- Gentoo-PerlMod-Version_: supports Perl package version checks
- tree-sitter-bash_: used in checks that inspect the CST of ebuilds and
eclasess. Must be language version >= 14.
Installing
==========
Installing latest pypi release::
pip install pkgcheck
Installing from git::
pip install https://github.com/pkgcore/pkgcheck/archive/master.tar.gz
Installing from a tarball::
python setup.py install
Usage
=====
Most users will use pkgcheck on the command line via ``pkgcheck scan`` to
target ebuild repos. See the docs_ or the man page for more information on
running pkgcheck.
It's also possible to run pkgcheck natively from python. For example, to output
the results for a given ebuild repo:
.. code-block:: python
from pkgcheck import scan
for result in scan(['/path/to/ebuild/repo']):
print(result)
This allows third party tools written in python to leverage pkgcheck's scanning
functionality for purposes such as CI or VCS commit support.
Tests
=====
Normal pytest is used, just execute::
pytest
In addition, a tox config is provided so the testsuite can be run in a
virtualenv setup against all supported python versions. To run tests for all
environments just execute **tox** in the root directory of a repo or unpacked
tarball. Otherwise, for a specific python version execute something similar to
the following::
tox -e py311
Adding new checks
=================
Adding a new check consists of 2 main parts: writing the logic and
documentation, and adding tests for the check.
Writing the logic
-----------------
1. Select the best file for the check under ``src/pkgcheck/checks/``.
2. Create new classes for the results:
- You would need to select the correct result level (style, info, warning,
error) - you might want to consult QA team.
- You would need to select the correct context: category, package, version,
profile, etc.
- Add long user friendly documentation for the result.
- Implement the ``desc`` property which is printed to the user.
3. Create a new class for the check:
- Add long user friendly documentation for the result.
- Put the source of input for the check. This is hard, so best case is to
find similar check and copy the code.
- Define the results it can return.
- Implement the ``feed`` function.
Adding tests
------------
1. Select one of the repos under ``testdata/repos``. In most cases you would
want ``standalone``.
2. Add the ebuild/category/test case you want to catch.
3. ``cd`` into this directory, and run ``pkgcheck scan --cache-dir /tmp -R JsonStream``.
This should yield the results you want to catch (filter out what you expect).
4. Add the results to the test case under:
``testdata/data/repos/${REPO}/${CHECK CLASS}/${RESULT CLASS}/expected.json``
5. If you want to check the fix for the test case, ``git add`` the files under
``testdata/repos/${REPO}``, modify to fix the results, and using
``git diff testdata/repos/${REPO}`` collect the diff.
6. Copy similar patch, add the diff to the patch file, and fix file names, under:
``testdata/data/repos/${REPO}/${CHECK CLASS}/${RESULT CLASS}/fix.patch``
.. _pkgcore: https://github.com/pkgcore/pkgcore
.. _snakeoil: https://github.com/pkgcore/snakeoil
.. _dependencies: https://github.com/pkgcore/pkgcheck/blob/master/requirements/install.txt
.. _git: https://git-scm.com/
.. _requests: https://pypi.org/project/requests/
.. _Gentoo-PerlMod-version: https://metacpan.org/release/Gentoo-PerlMod-Version
.. _tree-sitter-bash: https://github.com/tree-sitter/tree-sitter-bash
.. _docs: https://pkgcore.github.io/pkgcheck/man/pkgcheck.html
.. |pypi| image:: https://img.shields.io/pypi/v/pkgcheck.svg
:target: https://pypi.python.org/pypi/pkgcheck
.. |test| image:: https://github.com/pkgcore/pkgcheck/workflows/test/badge.svg
:target: https://github.com/pkgcore/pkgcheck/actions?query=workflow%3A%22test%22
.. |coverage| image:: https://codecov.io/gh/pkgcore/pkgcheck/branch/master/graph/badge.svg
:target: https://codecov.io/gh/pkgcore/pkgcheck