# Black GitLab Code Quality
This project aim to convert [Black](https://github.com/psf/black) report to
[CodeClimate](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md)
format that can be ingest by GitLab.
```
→ poetry run black-gl-cq src/black_gl_code_quality | jq
[
{
"type": "issue",
"description": "Black would reformat",
"location": {
"lines": {
"begin": 1,
"end": 1
},
"path": "src/black_gl_code_quality/__main__.py"
},
"severity": "major"
},
{
"type": "issue",
"description": "Black would reformat",
"location": {
"lines": {
"begin": 1,
"end": 1
},
"path": "src/black_gl_code_quality/error.py"
},
"severity": "major"
}
]
```
## Motivation
For security concerns, Docker-in-Docker has been disabled in all GitLab runners that I
have access/manage. Because the Code Quality template shipped with GitLab instances use
CodeClimate CLI that requires a Docker environment, we can't use it and an alternative
solution was required to obtain Black errors in our Code Quality reports.
## How to install
Simply run the following command:
```
pip install black-gl-code-quality
```
If you use Poetry, you can add it to your dev-dependencies:
```
poetry add --group dev black-gl-code-quality
```
## Usage
There is two ways to use this tool:
- by piping Black
- by calling `black-gl-code-quality` (or by it's alias `black-gl-cq`) directly
### Piping with Black
Piping with Black requires to forward `stderr` to `stdout`. You can use the following
command in the `.gitlab-ci.yml`:
```
black --check src/ 2>&1 | black-gl-cq > black-code-quality-report.json
```
Here's an example for a GitLab-CI job:
```yaml
lint:black:
stage: test
script:
- source .venv/bin/activate
- black --check src/ 2>&1 | black-gl-cq > black-code-quality-report.json
artifacts:
when: always
reports:
codequality: black-code-quality-report.json
```
### Calling `black-gl-code-quality` directly
Calling `black-gl-code-quality` (or it's alias `black-gl-cq`) execute Black with the
`--check` argument. It forwards all arguments you pass if you need to configure Black
via the CLI.
Specifying source folders is **MANDATORY**.
Here's an example for a GitLab-CI job:
```yaml
lint:black:
stage: test
script:
- source .venv/bin/activate
- black-gl-cq src/ > black-code-quality-report.json
artifacts:
when: always
reports:
codequality: black-code-quality-report.json
```
Admit we want to skip string normalization:
```yaml
lint:black:
stage: test
script:
- source .venv/bin/activate
- black-gl-cq -S src/ > black-code-quality-report.json
artifacts:
when: always
reports:
codequality: black-code-quality-report.json
```
### Change severity
By default, all errors have the severity `major`. Depending how you consider Black issues
important, you can change the severity for all errors returned by the report by using
one of the following [values](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#issues)
with the `BLACK_GL_SEVERITY` environment variable: `info`, `minor`, `major`, `critical`, `blocker`.
Here's an example for a GitLab-CI job:
```yaml
lint:black:
stage: test
variables:
BLACK_GL_SEVERITY: minor
script:
- source .venv/bin/activate
- black-gl-cq src/ > black-code-quality-report.json
artifacts:
when: always
reports:
codequality: black-code-quality-report.json
```
### Debugging
It is possible to pass the `-v` argument to `black-gl-cq` to stream Black's output to stderr.
Here's an example:
```
$ poetry run black-gl-cq -v src > black-code-quality-report.json
Identified `/home/themimitoof/repos/black-gl-code-quality` as project root containing a .git directory.
Sources to be formatted: "src"
/home/themimitoof/repos/black-gl-code-quality/src/black_gl_code_quality/__init__.py wasn't modified on disk since last run.
/home/themimitoof/repos/black-gl-code-quality/src/black_gl_code_quality/parser.py wasn't modified on disk since last run.
/home/themimitoof/repos/black-gl-code-quality/src/black_gl_code_quality/error.py already well formatted, good job.
/home/themimitoof/repos/black-gl-code-quality/src/black_gl_code_quality/__main__.py already well formatted, good job.
All done! ✨ 🍰 ✨
4 files would be left unchanged.
```
## Contributions
In case you have a suggestion or want a new feature, feel free to open a
[discussion](https://github.com/Themimitoof/black-gl-code-quality/discussions).
If you found a bug, you can [open an issue](https://github.com/Themimitoof/black-gl-code-quality/issues).
In order to maintain an overall good code quality, this project use the following tools:
- [Black](https://github.com/psf/black)
- [Isort](https://github.com/PyCQA/isort)
- [Flake8](https://flake8.pycqa.org/en/latest/)
Linting and formatting tools are configured to match the [current default rules of Black](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html).
Please ensure to run these tools before commiting and submiting a Pull request. In case one of
these mentionned tools report an error, the CI will automatically fail.
In case you are able to fix by yourself a bug, enhance the code or implement a new
feature, feel free to send a [Pull request](https://github.com/Themimitoof/black-gl-code-quality/pulls).
## License
This project is released under the [BSD-3 Clause](LICENSE). Feel free to use,
contribute, fork and do what you want with it. Please keep all licenses, copyright
notices and mentions in case you use, re-use, steal, fork code from this repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/themimitoof/black-gl-code-quality",
"name": "black-gl-code-quality",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": null,
"keywords": "Black, CodeClimate, GitLab, GitLab-CI, Code Quality",
"author": "Michael Vieira",
"author_email": "dev@mvieira.fr",
"download_url": "https://files.pythonhosted.org/packages/b0/28/a5b0d5d1d554107b875df188b1902bb4b917dfa4abfa2f1834963885d7e9/black_gl_code_quality-0.3.0.tar.gz",
"platform": null,
"description": "# Black GitLab Code Quality\n\nThis project aim to convert [Black](https://github.com/psf/black) report to\n[CodeClimate](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md)\nformat that can be ingest by GitLab.\n\n```\n\u2192 poetry run black-gl-cq src/black_gl_code_quality | jq\n[\n {\n \"type\": \"issue\",\n \"description\": \"Black would reformat\",\n \"location\": {\n \"lines\": {\n \"begin\": 1,\n \"end\": 1\n },\n \"path\": \"src/black_gl_code_quality/__main__.py\"\n },\n \"severity\": \"major\"\n },\n {\n \"type\": \"issue\",\n \"description\": \"Black would reformat\",\n \"location\": {\n \"lines\": {\n \"begin\": 1,\n \"end\": 1\n },\n \"path\": \"src/black_gl_code_quality/error.py\"\n },\n \"severity\": \"major\"\n }\n]\n```\n\n## Motivation\n\nFor security concerns, Docker-in-Docker has been disabled in all GitLab runners that I\nhave access/manage. Because the Code Quality template shipped with GitLab instances use\nCodeClimate CLI that requires a Docker environment, we can't use it and an alternative\nsolution was required to obtain Black errors in our Code Quality reports.\n\n\n## How to install\n\nSimply run the following command:\n\n```\npip install black-gl-code-quality\n```\n\nIf you use Poetry, you can add it to your dev-dependencies:\n\n```\npoetry add --group dev black-gl-code-quality\n```\n\n## Usage\n\nThere is two ways to use this tool:\n\n - by piping Black\n - by calling `black-gl-code-quality` (or by it's alias `black-gl-cq`) directly\n\n\n### Piping with Black\n\nPiping with Black requires to forward `stderr` to `stdout`. You can use the following\ncommand in the `.gitlab-ci.yml`:\n\n```\nblack --check src/ 2>&1 | black-gl-cq > black-code-quality-report.json\n```\n\nHere's an example for a GitLab-CI job:\n\n```yaml\nlint:black:\n stage: test\n script:\n - source .venv/bin/activate\n - black --check src/ 2>&1 | black-gl-cq > black-code-quality-report.json\n artifacts:\n when: always\n reports:\n codequality: black-code-quality-report.json\n```\n\n### Calling `black-gl-code-quality` directly\n\nCalling `black-gl-code-quality` (or it's alias `black-gl-cq`) execute Black with the\n`--check` argument. It forwards all arguments you pass if you need to configure Black\nvia the CLI.\n\nSpecifying source folders is **MANDATORY**.\n\nHere's an example for a GitLab-CI job:\n\n```yaml\nlint:black:\n stage: test\n script:\n - source .venv/bin/activate\n - black-gl-cq src/ > black-code-quality-report.json\n artifacts:\n when: always\n reports:\n codequality: black-code-quality-report.json\n```\n\nAdmit we want to skip string normalization:\n\n```yaml\nlint:black:\n stage: test\n script:\n - source .venv/bin/activate\n - black-gl-cq -S src/ > black-code-quality-report.json\n artifacts:\n when: always\n reports:\n codequality: black-code-quality-report.json\n```\n\n### Change severity\n\nBy default, all errors have the severity `major`. Depending how you consider Black issues\nimportant, you can change the severity for all errors returned by the report by using\none of the following [values](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#issues)\nwith the `BLACK_GL_SEVERITY` environment variable: `info`, `minor`, `major`, `critical`, `blocker`.\n\nHere's an example for a GitLab-CI job:\n\n```yaml\nlint:black:\n stage: test\n variables:\n BLACK_GL_SEVERITY: minor\n script:\n - source .venv/bin/activate\n - black-gl-cq src/ > black-code-quality-report.json\n artifacts:\n when: always\n reports:\n codequality: black-code-quality-report.json\n```\n\n### Debugging\n\nIt is possible to pass the `-v` argument to `black-gl-cq` to stream Black's output to stderr.\n\nHere's an example:\n\n```\n$ poetry run black-gl-cq -v src > black-code-quality-report.json\nIdentified `/home/themimitoof/repos/black-gl-code-quality` as project root containing a .git directory.\nSources to be formatted: \"src\"\n/home/themimitoof/repos/black-gl-code-quality/src/black_gl_code_quality/__init__.py wasn't modified on disk since last run.\n/home/themimitoof/repos/black-gl-code-quality/src/black_gl_code_quality/parser.py wasn't modified on disk since last run.\n/home/themimitoof/repos/black-gl-code-quality/src/black_gl_code_quality/error.py already well formatted, good job.\n/home/themimitoof/repos/black-gl-code-quality/src/black_gl_code_quality/__main__.py already well formatted, good job.\n\nAll done! \u2728 \ud83c\udf70 \u2728\n4 files would be left unchanged.\n```\n\n## Contributions\n\nIn case you have a suggestion or want a new feature, feel free to open a\n[discussion](https://github.com/Themimitoof/black-gl-code-quality/discussions).\n\nIf you found a bug, you can [open an issue](https://github.com/Themimitoof/black-gl-code-quality/issues).\n\nIn order to maintain an overall good code quality, this project use the following tools:\n\n - [Black](https://github.com/psf/black)\n - [Isort](https://github.com/PyCQA/isort)\n - [Flake8](https://flake8.pycqa.org/en/latest/)\n\nLinting and formatting tools are configured to match the [current default rules of Black](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html).\n\nPlease ensure to run these tools before commiting and submiting a Pull request. In case one of\nthese mentionned tools report an error, the CI will automatically fail.\n\nIn case you are able to fix by yourself a bug, enhance the code or implement a new\nfeature, feel free to send a [Pull request](https://github.com/Themimitoof/black-gl-code-quality/pulls).\n\n## License\n\nThis project is released under the [BSD-3 Clause](LICENSE). Feel free to use,\ncontribute, fork and do what you want with it. Please keep all licenses, copyright\nnotices and mentions in case you use, re-use, steal, fork code from this repository.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A simple wrapper to convert Black outputs to codeclimate report format for GitLab-CI",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/themimitoof/black-gl-code-quality",
"Repository": "https://github.com/themimitoof/black-gl-code-quality"
},
"split_keywords": [
"black",
" codeclimate",
" gitlab",
" gitlab-ci",
" code quality"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "01850b9aa33cc33ac45d8d96524394b0d31ca216d4c1d5eac00a4417efe5a752",
"md5": "e5e4fd8ebca8fafa3674d7ffda18ee8f",
"sha256": "b6305179e8f668275a766ae3c6f7839f23ebe3c37c557a75979caebbf42a7ddd"
},
"downloads": -1,
"filename": "black_gl_code_quality-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e5e4fd8ebca8fafa3674d7ffda18ee8f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 6355,
"upload_time": "2024-08-13T15:12:42",
"upload_time_iso_8601": "2024-08-13T15:12:42.383996Z",
"url": "https://files.pythonhosted.org/packages/01/85/0b9aa33cc33ac45d8d96524394b0d31ca216d4c1d5eac00a4417efe5a752/black_gl_code_quality-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b028a5b0d5d1d554107b875df188b1902bb4b917dfa4abfa2f1834963885d7e9",
"md5": "468e195317c02f7e98a5253bf2025ba7",
"sha256": "d575a39d40b4d65919093d16e8d76afaa7357de06c36977c691fcf79f142d76f"
},
"downloads": -1,
"filename": "black_gl_code_quality-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "468e195317c02f7e98a5253bf2025ba7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 4952,
"upload_time": "2024-08-13T15:12:44",
"upload_time_iso_8601": "2024-08-13T15:12:44.037708Z",
"url": "https://files.pythonhosted.org/packages/b0/28/a5b0d5d1d554107b875df188b1902bb4b917dfa4abfa2f1834963885d7e9/black_gl_code_quality-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-13 15:12:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "themimitoof",
"github_project": "black-gl-code-quality",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "black-gl-code-quality"
}
JSON
