# pylint-exit
[](https://pypi.org/project/pylint-exit)
[](https://travis-ci.org/jongracecox/pylint-exit)
[](https://pypistats.org/packages/pylint-exit)
[](https://github.com/jongracecox/pylint-exit/commits/master)
[](https://github.com/jongracecox/pylint-exit/blob/master/LICENSE)
[](https://github.com/jongracecox/pylint-exit/stargazers)
Utility to handle pylint exit codes on Linux in a scripting-friendly way.
Pylint uses bit-encoded exit codes to convey the results of the pylint review,
which means it will return with a non-zero return code even when the
pylint scoring was successful.
This can make it difficult to script the execution of pylint while at the same time
detecting genuine errors.
`pylint-exit` is a small command-line utility that can be used to re-process
the pylint return code and translate it into a scripting-friendly return code.
`pylint-exit` will decode the bit-encoded return code, identify whether there were
any fatal messages issued (which might constitute a failure in the execution of
pylint), or a usage error, and return a `0` or `1` return code that is more easily
used in shell scripts.
# Installation
The simplest way to install is via `pip`.
```bash
pip install pylint-exit
```
This will install the package, and will provide the `pylint-exit` command line utility.
You can also manually install by downloading `pylint_exit.py`, and make it executable.
```bash
curl -o pylint-exit https://raw.githubusercontent.com/jongracecox/pylint-exit/master/pylint_exit.py && chmod +x pylint_exit.py
```
You should also consider creating a symbolic link so that the calls in the remainder of this
README work as described. Update `<path-to>` with where you downloaded the script.
```bash
ln -s <path-to>/pylint_exit.py /usr/local/bin/pylint-exit
```
*Note: If you perform a `--user` install with `pip` then you will need to ensure `~/.local/bin` appears in your `PATH`
environment variable, otherwise the command line `pylint-exit` will not work.*
# Usage
Add `|| pylint-exit $?` to the end of your existing Pylint command. You can then
use the updated `$?` return code in your shell script.
```bash
pylint mymodule.py || pylint-exit $?
if [ $? -ne 0 ]; then
echo "An error occurred while running pylint." >&2
exit 1
fi
```
Note: Many CI tools will check the return code of each command, so it may be enough to
simply add `|| pylint-exit $?`, and leave the return code check to the CI executor.
You can also use the python code directly if needed:
```bash
pylint mymodule.py || python pylint_exit.py $?
```
# Return codes
Pylint can return combinations of the following codes. `pylint-exit` will identify each
issued message, and return the maximum final return code.
| Pylint code | Message | Final return code |
| ----------- | ------- | ----------------- |
| 1 | Fatal message issued | 1 |
| 2 | Error message issued | 0 |
| 4 | Warning message issued | 0 |
| 8 | Refactor message issued | 0 |
| 16 | Convention message issued | 0 |
| 32 | Usage error | 1 |
This list is stored in `exit_codes_list`, which can be customised if needed.
You can control what is considered a failure using the following command line arguments.
By default these types of messages don't cause a non-zero return code. Adding
any of these arguments will trigger a non-zero return code when those types of
message are raised.
| Name | Meaning |
| ---- | ------- |
| `-efail`, `--error-fail` | Fail on issued error messages. |
| `-wfail`, `--warn-fail` | Fail on issued warning messages. |
| `-rfail`, `--refactor-fail` | Fail on issued refactor messages. |
| `-cfail`, `--convention-fail` | Fail on issued convension messages. |
# Examples
## Exiting gracefully on non-severe messages
In this example pylint issues refactor and convention messages, and exits with a
return code of 24. `pylint-exit` decodes this, displays the messages, and exits
with a return code of 0.
```bash
> pylint --rcfile=.pylintrc --output-format=text mymodule.py || pylint-exit $?
The following messages were raised:
- refactor message issued
- convention message issued
No fatal messages detected. Exiting gracefully...
> echo $?
0
```
## Exiting with an error on severe messages
In this example pylint returns with a usage error due to the bad output format, and
exits with a return code of 32. `pylint-exit` detects this, displays the message, and
returns with an exit code of 1.
```bash
> pylint --rcfile=.pylintrc --output-format=badformat mymodule.py || pylint-exit $?
The following messages were raised:
- usage error
Fatal messages detected. Failing...
> echo $?
1
```
## Treating errors and warnings as severe
In this example we will use the `--error-fail` and `--warn-fail` command line arguments
to cause pylint-exit to treat errors and warnings as serious enough to return a non-zero
return code.
In the example scenario pylint issues error and warning messages, and exits with a
return code of 6. `pylint-exit` decodes this, displays the messages, and exits
with a return code of 1 because the error and warning messages are now considered as
fatal.
```bash
> pylint --rcfile=.pylintrc --output-format=badformat mymodule.py || pylint-exit --error-fail --warn-fail $?
The following messages were raised:
- error message issued
- warning message issued
Fatal messages detected. Failing...
> echo $?
1
```
# Testing
You can test how pylint-exit will react to various return codes using the following command:
```bash
(exit 6) || pylint-exit $?
```
or if you are using the python code directly:
```bash
(exit 6) || python pylint_exit.py $?
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jongracecox/pylint-exit",
"name": "pylint-exit",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Jon Grace-Cox",
"author_email": "jongracecox@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/26/fb/4365157ab89cd442cca4714595466394d5ee328709ca1804a5c85be7ae32/pylint-exit-1.2.0.zip",
"platform": "",
"description": "# pylint-exit\n\n[](https://pypi.org/project/pylint-exit)\n[](https://travis-ci.org/jongracecox/pylint-exit)\n[](https://pypistats.org/packages/pylint-exit)\n[](https://github.com/jongracecox/pylint-exit/commits/master)\n[](https://github.com/jongracecox/pylint-exit/blob/master/LICENSE)\n[](https://github.com/jongracecox/pylint-exit/stargazers)\n\nUtility to handle pylint exit codes on Linux in a scripting-friendly way.\n\nPylint uses bit-encoded exit codes to convey the results of the pylint review,\nwhich means it will return with a non-zero return code even when the\npylint scoring was successful.\n\nThis can make it difficult to script the execution of pylint while at the same time\ndetecting genuine errors.\n\n`pylint-exit` is a small command-line utility that can be used to re-process\nthe pylint return code and translate it into a scripting-friendly return code.\n\n`pylint-exit` will decode the bit-encoded return code, identify whether there were\nany fatal messages issued (which might constitute a failure in the execution of\npylint), or a usage error, and return a `0` or `1` return code that is more easily\nused in shell scripts.\n\n# Installation\n\nThe simplest way to install is via `pip`.\n\n```bash\npip install pylint-exit\n```\n\nThis will install the package, and will provide the `pylint-exit` command line utility.\n\nYou can also manually install by downloading `pylint_exit.py`, and make it executable.\n\n```bash\ncurl -o pylint-exit https://raw.githubusercontent.com/jongracecox/pylint-exit/master/pylint_exit.py && chmod +x pylint_exit.py\n```\n\nYou should also consider creating a symbolic link so that the calls in the remainder of this\nREADME work as described. Update `<path-to>` with where you downloaded the script.\n\n```bash\nln -s <path-to>/pylint_exit.py /usr/local/bin/pylint-exit\n```\n\n*Note: If you perform a `--user` install with `pip` then you will need to ensure `~/.local/bin` appears in your `PATH`\nenvironment variable, otherwise the command line `pylint-exit` will not work.* \n\n# Usage\nAdd `|| pylint-exit $?` to the end of your existing Pylint command. You can then\nuse the updated `$?` return code in your shell script.\n\n```bash\npylint mymodule.py || pylint-exit $?\nif [ $? -ne 0 ]; then\n echo \"An error occurred while running pylint.\" >&2\n exit 1\nfi\n```\n\nNote: Many CI tools will check the return code of each command, so it may be enough to\nsimply add `|| pylint-exit $?`, and leave the return code check to the CI executor.\n\nYou can also use the python code directly if needed:\n\n```bash\npylint mymodule.py || python pylint_exit.py $?\n```\n\n# Return codes\nPylint can return combinations of the following codes. `pylint-exit` will identify each\nissued message, and return the maximum final return code.\n\n| Pylint code | Message | Final return code |\n| ----------- | ------- | ----------------- |\n| 1 | Fatal message issued | 1 |\n| 2 | Error message issued | 0 |\n| 4 | Warning message issued | 0 |\n| 8 | Refactor message issued | 0 |\n| 16 | Convention message issued | 0 |\n| 32 | Usage error | 1 |\n\nThis list is stored in `exit_codes_list`, which can be customised if needed.\n\nYou can control what is considered a failure using the following command line arguments.\nBy default these types of messages don't cause a non-zero return code. Adding\nany of these arguments will trigger a non-zero return code when those types of\nmessage are raised. \n\n| Name | Meaning |\n| ---- | ------- |\n| `-efail`, `--error-fail` | Fail on issued error messages. |\n| `-wfail`, `--warn-fail` | Fail on issued warning messages. |\n| `-rfail`, `--refactor-fail` | Fail on issued refactor messages. |\n| `-cfail`, `--convention-fail` | Fail on issued convension messages. |\n\n# Examples\n\n## Exiting gracefully on non-severe messages\nIn this example pylint issues refactor and convention messages, and exits with a\nreturn code of 24. `pylint-exit` decodes this, displays the messages, and exits\nwith a return code of 0.\n\n```bash\n> pylint --rcfile=.pylintrc --output-format=text mymodule.py || pylint-exit $?\nThe following messages were raised:\n\n - refactor message issued\n - convention message issued\n\nNo fatal messages detected. Exiting gracefully...\n> echo $?\n0\n```\n\n## Exiting with an error on severe messages\nIn this example pylint returns with a usage error due to the bad output format, and\nexits with a return code of 32. `pylint-exit` detects this, displays the message, and\nreturns with an exit code of 1.\n\n```bash\n> pylint --rcfile=.pylintrc --output-format=badformat mymodule.py || pylint-exit $?\nThe following messages were raised:\n\n - usage error\n\nFatal messages detected. Failing...\n> echo $?\n1\n```\n\n## Treating errors and warnings as severe\nIn this example we will use the `--error-fail` and `--warn-fail` command line arguments\nto cause pylint-exit to treat errors and warnings as serious enough to return a non-zero\nreturn code.\n\nIn the example scenario pylint issues error and warning messages, and exits with a\nreturn code of 6. `pylint-exit` decodes this, displays the messages, and exits\nwith a return code of 1 because the error and warning messages are now considered as\nfatal.\n\n\n```bash\n> pylint --rcfile=.pylintrc --output-format=badformat mymodule.py || pylint-exit --error-fail --warn-fail $?\nThe following messages were raised:\n\n - error message issued\n - warning message issued\n\nFatal messages detected. Failing...\n> echo $?\n1\n\n```\n\n# Testing\n\nYou can test how pylint-exit will react to various return codes using the following command:\n\n```bash\n(exit 6) || pylint-exit $?\n```\n\nor if you are using the python code directly:\n\n```bash\n(exit 6) || python pylint_exit.py $?\n```\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Exit code handler for pylint command line utility.",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/jongracecox/pylint-exit"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "94ed5d45bbd42d5407250dd46ce1b9c098d612c3a9bb538858d09da2df77c961",
"md5": "d942ed3bb694023e4592cc7861e47d76",
"sha256": "65c9e7856e9058705a92d7c45628d604b2a4b8ee2b3c18a7303be77f9ed87cbe"
},
"downloads": -1,
"filename": "pylint_exit-1.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d942ed3bb694023e4592cc7861e47d76",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6340,
"upload_time": "2020-07-15T22:18:00",
"upload_time_iso_8601": "2020-07-15T22:18:00.110977Z",
"url": "https://files.pythonhosted.org/packages/94/ed/5d45bbd42d5407250dd46ce1b9c098d612c3a9bb538858d09da2df77c961/pylint_exit-1.2.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "26fb4365157ab89cd442cca4714595466394d5ee328709ca1804a5c85be7ae32",
"md5": "3f60dde538f28282024ba1a52a668cb2",
"sha256": "b6ad02884c01c5560a5275079fe5a6c792afff90ecccf0c02513e1547ee280b0"
},
"downloads": -1,
"filename": "pylint-exit-1.2.0.zip",
"has_sig": false,
"md5_digest": "3f60dde538f28282024ba1a52a668cb2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11093,
"upload_time": "2020-07-15T22:18:01",
"upload_time_iso_8601": "2020-07-15T22:18:01.006470Z",
"url": "https://files.pythonhosted.org/packages/26/fb/4365157ab89cd442cca4714595466394d5ee328709ca1804a5c85be7ae32/pylint-exit-1.2.0.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-07-15 22:18:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jongracecox",
"github_project": "pylint-exit",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pylint-exit"
}
JSON
