Pylint JSON to HTML Converter

Common errors

• Error: no such option: --output-format=html

  cause Attempting to use `--output-format=html` directly with Pylint versions 1.7 or newer.
  fix Pylint no longer supports direct HTML output. Instead, generate JSON output (`--output-format=json`) and pipe it to `pylint-json2html`. Example: `pylint my_module.py --output-format=json | pylint-json2html -o report.html`.

• Blank or incomplete HTML report file generated.

  cause Pylint's output was not correctly formatted as JSON, or `pylint-json2html` did not receive any input.
  fix Verify that Pylint is configured to output JSON (`--output-format=json`) and that its output is successfully piped to `pylint-json2html` (e.g., check for errors in the Pylint command itself). Make sure to pass the output file with `-o <filename>.html`.

• UnicodeEncodeError: 'charmap' codec can't encode character...

  cause Piping Pylint's output to `pylint-json2html` in a terminal/environment with a non-UTF-8 default encoding, leading to character encoding mismatches.
  fix Run `pylint-json2html` with the output encoding flag: `pylint ... | pylint-json2html -o report.html -e utf-8`. Also, ensure your terminal supports UTF-8, and consider setting `PYTHONIOENCODING=utf-8`.

• pylint-json2html: error: the following arguments are required: FILENAME

  cause `pylint-json2html` expects a filename as input or data from stdin, but received neither.
  fix Ensure you either pipe Pylint's JSON output directly to `pylint-json2html` or provide a JSON filename as a positional argument. Correct usage: `pylint my_file.py --output-format=json | pylint-json2html -o report.html` OR `pylint my_file.py --output-format=json > report.json; pylint-json2html report.json -o report.html`.

Warnings

• breaking Pylint removed its native HTML output format starting from version 1.7. `pylint-json2html` was created to provide this functionality externally. Users upgrading Pylint from versions older than 1.7 will need this or a similar tool to continue generating HTML reports.
  Fix: Install `pylint-json2html` and pipe Pylint's JSON output to it, or use a similar third-party tool.
• gotcha The `pylint-json2html` tool requires Pylint's output to be in JSON format. Forgetting to specify `--output-format=json` (or `output-format=json` in `.pylintrc`) will result in `pylint-json2html` failing to process the input or generating an empty/malformed HTML report.
  Fix: Ensure Pylint is run with `--output-format=json` or `--output-format=jsonextended` (for more data) when generating input for `pylint-json2html`. For example: `pylint your_module.py --output-format=json | pylint-json2html -o report.html`.
• gotcha When piping Pylint's output, especially in environments with non-UTF-8 default encodings (e.g., `cp1252` or `latin1`), character encoding issues can lead to garbled text in the final HTML report.
  Fix: Explicitly set the output encoding using the `-e utf-8` flag for `pylint-json2html` and ensure your terminal/environment handles UTF-8 correctly. Also, consider setting Python's `PYTHONIOENCODING=utf-8` environment variable if piping issues persist.
• gotcha There are two main JSON input formats: `json` and `jsonextended`. The default `json` format contains only messages, while `jsonextended` includes additional metrics like score, number of analyzed statements, and dependencies. Using `jsonextended` requires Pylint to output this specific format and `pylint-json2html` to be informed via the `-f jsonextended` flag.
  Fix: If you need score or metrics in your HTML report, configure Pylint to output `jsonextended` (e.g., via a custom plugin or Pylint's `--output-format` if it supports it in newer versions, or use the tool's plugin capabilities if applicable) and then run `pylint-json2html -f jsonextended ...`.

Install

• pip install pylint-json2html Install stable version

Quickstart

This quickstart demonstrates the typical workflow: first, run Pylint on your code, ensuring its output format is set to JSON. Then, pipe this JSON output to `pylint-json2html`, redirecting its HTML output to a specified file. Alternatively, Pylint's output can be saved to a file and passed as an argument to `pylint-json2html`.

import subprocess
import os

# Create a dummy Python file to lint
with open('my_module.py', 'w') as f:
    f.write('def my_func():\n    """Missing docstring for function."""\n    pass\n')

# 1. Run Pylint to generate a JSON report
# We use a temporary file for Pylint's output, then read it.
# In a real scenario, you'd pipe directly: `pylint my_module.py --output-format=json | pylint-json2html -o report.html`
try:
    pylint_cmd = ['pylint', 'my_module.py', '--output-format=json', '--msg-template="{path}:{line}:{column}: {msg_id}: {msg} ({symbol})"']
    pylint_process = subprocess.run(pylint_cmd, capture_output=True, text=True, check=True)
    pylint_json_output = pylint_process.stdout
    
    # Save Pylint's JSON output to a temporary file for demonstration
    with open('pylint_report.json', 'w') as f:
        f.write(pylint_json_output)

    # 2. Convert the JSON report to HTML using pylint-json2html
    # Note: pylint-json2html is typically used via piping, but for programmatic demo, 
    # we simulate input from a file or directly pass content if possible (which it is via stdin for the CLI tool).
    # For this example, we'll run it as a separate command reading the file.
    html_cmd = ['pylint-json2html', 'pylint_report.json', '-o', 'pylint_report.html']
    subprocess.run(html_cmd, check=True)

    print("HTML report generated at pylint_report.html")
    print("JSON report saved at pylint_report.json")

except subprocess.CalledProcessError as e:
    print(f"An error occurred during pylint or pylint-json2html execution: {e.stderr}")
except FileNotFoundError:
    print("Error: Pylint or pylint-json2html command not found. Ensure they are installed and in your PATH.")
finally:
    # Clean up dummy files
    if os.path.exists('my_module.py'):
        os.remove('my_module.py')
    if os.path.exists('pylint_report.json'):
        os.remove('pylint_report.json')
    # The generated HTML report is left for inspection
    # if os.path.exists('pylint_report.html'):
    #     os.remove('pylint_report.html') # Uncomment to remove HTML as well