panoptipy

A Package for the Static Code Quality Assessment of Python codebases. It scans local codebases or remote GitHub repositories and generates a report summarising various code quality metrics.

Quickstart

The main way to use panoptipy is through its command-line interface. Here's how to scan a Python codebase that is in the "project" directory:

# Basic scan with default settings
$ panoptipy scan /path/to/project

To run on multiple directories, you can specify them as a space-separated list:

# Scan multiple directories
$ panoptipy scan /path/to/project1 /path/to/project2

You can also use wildcards to specify directories:

# Scan all directories in the current directory
$ panoptipy scan ./*

Using the scan command in this way will:

• Load all configured checks (there's a list below)
• Analyse your codebase
• Generate a report with the results
• Output the report to the console (by default)

The scan report shows:

• Overall codebase rating (Gold, Silver, Bronze, or Problematic)
• A summary of whether each individual check passed or not
• Detailed information about any failures

What is panoptipy for?

There is a lot of overlap between panoptipy and pre-commit (with the relevant hooks). So what are the differences?

• pre-commit is meant to be used by developers to check their own code before they commit it or in Continuous Integration (CI) / Continous Deployment (CD) pipelines.
• panoptipy has features that help the leaders and managers of other developers. To that end it can summarise the results of many code repos at once.
• panoptipy can be be used to generate and export reports in a variety of formats (JSON, parquet) for further analysis.

These packages are similar in that they can both be used in CI/CD pipelines but pre-commit should be your first port of call for that and is not only more geared to that use, but also far more mature.

Installation

You can use panoptipy as a stand-alone tool via Astral's uv package:

uvx panoptipy scan .

Alternatively, you can install it as a Python package with pip install or uv add.

To install the development version from git, use:

pip install git+https://github.com/aeturrell/panoptipy.git

Documentation

You can find the full documentation for panoptipy at https://aeturrell.github.io/panoptipy/.