Error Catalog

An IntelliJ Platform plugin (PyCharm and other JetBrains IDEs) for generating standardized API error codes without leaving the editor.

The plugin finds your project's error catalog, picks the next free code, appends a define_error(...) declaration to the correct file, and fills the AppError(...) call at the caret with the new code and its imports.

What it does

When you are about to raise an application error, you usually need to:

1. Choose a code that follows the catalog's naming scheme.
2. Find the next free number for that category.
3. Add a define_error(...) declaration in the right file.
4. Import the code and AppError, then write the raise statement.

This plugin does all four from a single dialog.

How it works

The catalog convention it expects:

• A taxonomy.py reference file that defines the available keys:

  CATEGORIES: dict[str, Category] = {
      "A": Category("access", 401),
      "V": Category("validation", 400),
      # ...
  }
  DOMAINS: dict[str, str] = {
      "U": "users",
      "O": "orders",
      # ...
  }
  LAYERS: dict[str, str] = {
      "S": "service",
      "R": "serializer",
      # ...
  }

• Error codes shaped as <Category><4 digits><Domain><Layer>, for example V0008UR.

• Declarations created through a define_error(...) factory, one file per domain and category:

  V0008UR = define_error(
      code="V0008UR",
      http=400,
      message="Login is already taken.",
      show_in_prod=False,
  )

The plugin locates the catalog by searching the project for taxonomy.py and parsing it. The Python import prefix (such as apps.api.common.exceptions) is derived from the catalog directory relative to its sources root, so it works with regular and namespace packages without any configuration.

Requirements

• A JetBrains IDE built on IntelliJ Platform 2024.2 or newer (build 242). The plugin declares compatibility through build 299.

Installation

From a packaged build:

1. Build the distribution (see below) or use a prebuilt error-catalog-intellij-<version>.zip.
2. In the IDE: Settings, Plugins, the gear icon, Install Plugin from Disk.
3. Select the zip and restart.

Usage

Open a Python file and use any of the entry points:

• Place the caret on a line that contains an AppError( call and press Alt+Enter, then choose "Create new error code".
• Press Alt+Insert (Generate) and choose "Error Code".
• Use Tools, Generate Error Code.

The dialog asks for:

• Category, domain, and layer, each shown with its human-readable name so the meaning of a letter is visible while choosing.
• HTTP status, blank to use the category default.
• The error message used in development and test environments.
• Whether the message is shown in production.

On confirmation the declaration is written to the catalog. If the caret is on a line with an AppError( call, that call is filled with the new code; otherwise a raise AppError(CODE) statement is added below the caret. The required imports are inserted at the top of the file when missing.

Building from source

./gradlew buildPlugin

The distribution is written to build/distributions/.

To try the plugin in a sandbox IDE:

./gradlew runIde

To run the unit tests:

./gradlew test

Project layout

src/main/kotlin/com/errorcatalog/
    ErrorCatalog.kt          taxonomy parsing, numbering, declaration writing
    CatalogLocator.kt        locates the catalog in the project
    GenerateErrorDialog.kt   the input dialog
    GenerateErrorCodeAction.kt  Generate and Tools entry points
    NewErrorIntention.kt     Alt+Enter entry point
    EditorInsert.kt          editor edits (call fill, raise, imports)
src/test/kotlin/com/errorcatalog/
    unit tests for the catalog logic

Changelog

See CHANGELOG.md.

License

MIT. See LICENSE.