Important

A Visual Studio Code extension that validates and formats Python import statements according to the Google Python Style Guide and PEP 8, with Ruff-compatible first-party module support. It provides real-time diagnostics as you type, highlights unused imports, and can automatically fix all issues including wildcard imports, incorrect ordering, and symbol imports. The extension scans your code to understand which imports are actually used and applies intelligent fixes that update both the import statements and all related symbol references throughout your file.

Features

Important helps you maintain clean, consistent Python imports by:

• Real-time validation - Issues are highlighted as you type
• Unused import detection - Faded highlighting for imports not used in your code
• Quick fixes - One-click "Fix All" for import problems
• Auto-fix all - Fix all issues and sort imports with a single command
• Smart sorting - Groups imports correctly and removes unused ones
• Multi-line formatting - Long imports are wrapped into Ruff-style parenthesised multi-line format
• if TYPE_CHECKING support - Symbol imports inside if TYPE_CHECKING: or if typing.TYPE_CHECKING: blocks are allowed; all other rules still apply and the block is sorted in-place
• Google Style Guide compliance - Enforces industry-standard import conventions

Validation Rules

Example

Before running "Fix Imports":

import requests
import os, sys
from os.path import *
from models.user import User
import json

print(abspath("."))
user = User()

After:

import json
import os
import sys

import requests

from models import user

print(os.path.abspath("."))
user = user.User()

Commands

Also available via Command Palette (Ctrl+Shift+P / Cmd+Shift+P) or right-click context menu.

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Important"
4. Click Install

Manual Installation (VSIX)

1. Download or build the .vsix file (see Building)
2. Open VS Code
3. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
4. Click the ... menu → Install from VSIX...
5. Select the .vsix file

Or via command line:

code --install-extension important-python-0.4.0.vsix

Configuration

Configure via VS Code Settings (Ctrl+, / Cmd+,):

Example settings.json

{
	"important.validateOnSave": true,
	"important.validateOnType": true,
	"important.styleGuide": "google",
	"important.knownFirstParty": ["myproject", "mypackage"],
	"important.readFromPyprojectToml": true,
	"important.lineLength": 0
}

Import Sorting

The "Fix Imports" command includes automatic import sorting that:

• Groups imports into 5 categories: __future__ → stdlib → third-party → first-party → local
• Sorts import statements before from statements within each group, then alphabetically by module name (ignoring case) — matching Ruff/isort default behaviour
• Sorts names within from imports using Ruff/isort order-by-type convention: CONSTANT_CASE names first, then CamelCase, then snake_case
• Splits multi-imports (import os, sys) into separate lines
• Removes unused imports (preserves __future__ directives)
• Merges duplicate imports (non-aliased only; each aliased from-import stays on its own line, matching Ruff)
• Fixes wildcard imports by converting to qualified module access
• Wraps long from imports into Ruff-style parenthesised multi-line format when they exceed the configured line length
• Sorts if TYPE_CHECKING: block imports in-place (same grouping & alphabetical rules, preserving block indentation)

First-Party Module Support

First-party modules are project-specific packages that should be grouped between third-party and local imports, matching Ruff's isort behaviour.

Automatic detection from pyproject.toml (enabled by default):

If your project has a pyproject.toml with a Ruff isort configuration, the extension automatically reads it:

[tool.ruff.lint.isort]
known-first-party = ["myproject", "mypackage"]

The extension watches for pyproject.toml changes and reloads automatically.

Monorepo support: The extension discovers every pyproject.toml in the workspace (excluding node_modules, .venv, and venv directories). Modules declared in a nested pyproject.toml are scoped — they only apply when validating Python files within that directory subtree. For example, a packages/api/pyproject.toml declaring known-first-party = ["api_core"] only affects files under packages/api/. Modules in the workspace-root pyproject.toml apply to all files.

Manual configuration via VS Code settings:

{
	"important.knownFirstParty": ["myproject", "mypackage"]
}

Modules configured via settings are global — they apply to every document regardless of path.

When both sources are active, global settings and scoped TOML entries are consulted together.

Resulting import order:

from __future__ import annotations

import os
import sys

import requests

from myproject import config
from myproject.models import base

from . import utils

Wildcard Import Fixing

Wildcard imports (from X import *) are automatically fixed for supported stdlib modules:

• os, os.path, sys
• re, json, collections
• typing, pathlib, datetime
• math, functools, itertools

The fix converts the import and updates all symbol usages:

# Before
from os.path import *
print(abspath("."))

# After
import os
print(os.path.abspath("."))

Non-Standard Alias Fixing

Non-standard import aliases are replaced with the recognised standard abbreviation (or the plain module name if no standard exists), and all references in code are updated:

# Before
import numpy as num
import os as operating_system
import datetime as date

arr = num.array([1, 2, 3])
print(operating_system.name)
now = date.datetime.now()

# After
import datetime as dt
import numpy as np
import os

arr = np.array([1, 2, 3])
print(os.name)
now = dt.datetime.now()

Alias-Aware Symbol Import Fixing

When fixing from X import Y as Z style symbol imports, the fixer correctly searches for the alias (not the original name) and replaces it with the qualified form:

# Before
from json import loads as json_loads
from collections import OrderedDict as OD

data = json_loads(text)
config = OD([("key", "value")])

# After
import collections
import json

data = json.loads(text)
config = collections.OrderedDict([("key", "value")])

Building

Prerequisites

• Node.js 18+
• npm 9+

Development Build

# Clone the repository
git clone https://github.com/irarainey/important.git
cd important

# Install dependencies
npm install

# Compile
npm run compile

# Run linter
npm run lint

Watch Mode

For development with auto-recompilation:

npm run watch

Package for Distribution

Create a .vsix file for manual installation:

npm run package

The package will be created in the output/package/ directory.

Project Structure

important/
├── src/
│   ├── extension.ts            		# Extension entry point & lifecycle
│   ├── types.ts                		# TypeScript type definitions
│   ├── providers/              		# VS Code language providers
│   │   ├── code-action-provider.ts  	# Quick fix code actions
│   │   └── hover-provider.ts        	# Hover information for diagnostics
│   ├── validation/              		# Import validation logic
│   │   ├── import-parser.ts        	# Import statement parsing
│   │   ├── import-validator.ts     	# Validation rules
│   │   ├── validation-cache.ts     	# Version-keyed validation cache
│   │   └── diagnostics.ts          	# Diagnostic conversion
│   ├── fixes/                   		# Import fixing logic
│   │   ├── fix-imports.ts          	# Fix all imports command
│   │   └── sort-imports.ts         	# Import sorting
│   └── utils/                  		# Utility modules
│       ├── logger.ts          			# Output channel logging
│       ├── module-resolver.ts  		# Workspace Python module detection
│       ├── module-symbols.ts   		# Known symbols for wildcard import fixing
│       ├── pyproject-reader.ts 		# Reads first-party config & line-length from pyproject.toml
│       ├── standard-aliases.ts 		# Well-known import alias mappings
│       ├── stdlib-modules.ts   		# Python standard library module list
│       └── text-utils.ts      			# Text/regex utilities, docstring detection
├── tests/
│   ├── application/                    # Sample Python project for manual testing
│   │   ├── other_library/              # First-party package (with nested modules)
│   │   │   ├── core/                   # BaseProcessor, exceptions
│   │   │   └── utils/                  # formatting, validation
│   │   └── src/
│   │       ├── main.py                 # Multiple issues: multi-imports, order, unused
│   │       ├── complex_example.py      # Aliases, multiline, deep namespace imports
│   │       ├── alias_examples.py       # Standard vs non-standard alias testing
│   │       ├── embedded_type_checking_example.py  # Embedded TC block between imports
│   │       ├── multiline_wrapping_example.py      # Line-length wrapping tests
│   │       ├── type_checking_example.py           # TYPE_CHECKING block tests
│   │       ├── services/api/handlers/  # Deep namespace test structure
│   │       ├── helpers/helpers.py      # Parent relative import, multiple imports
│   │       ├── models/sample_models.py # Clean file (no issues)
│   │       └── utils/utils.py          # Relative imports, symbol imports
│   └── unit/                           # Automated unit tests (Mocha)
│       ├── mocks/vscode.ts             # Custom vscode module mock
│       ├── import-parser.test.ts       # Import parsing (29 tests)
│       ├── import-validator.test.ts    # Validation rules (45 tests)
│       ├── module-resolver.test.ts     # Module resolution (15 tests)
│       ├── sort-imports.test.ts        # Import sorting (14 tests)
│       ├── diagnostics.test.ts         # Diagnostic conversion (11 tests)
│       ├── utils.test.ts               # Text utilities & stdlib (28 tests)
│       └── types.test.ts               # Type definitions (4 tests)
├── docs/
│   ├── ARCHITECTURE.md        			# Developer documentation
│   ├── GOOGLE-STYLE-GUIDE.md      		# Google Python Style Guide import rules reference
│   └── PEP8.md                    		# PEP 8 import standards reference
├── CHANGELOG.md               			# Release changelog
├── output/                    			# Compiled output (generated)
├── package.json               			# Extension manifest & dependencies
├── tsconfig.json              			# TypeScript configuration (ES2022 / esbuild)
├── tsconfig.test.json         			# TypeScript configuration for tests (CommonJS / Mocha)
├── .mocharc.yml               			# Mocha test runner configuration
└── eslint.config.mjs          			# ESLint configuration (with test overrides)

Development

Running in Debug Mode

1. Open the project in VS Code
2. Press F5 to launch Extension Development Host
3. The sample project (tests/application) opens automatically
4. Open any Python file to see import validation in action

The sample project includes intentional import violations for testing:

Unit Tests

The extension includes a comprehensive unit test suite (156 tests) covering all core modules. Tests run outside the VS Code extension host using a custom vscode module mock.

npm run test

The test infrastructure uses:

• Mocha as the test runner (configured via .mocharc.yml)
• Separate TypeScript config (tsconfig.test.json) compiling to CommonJS for Node.js/Mocha compatibility
• Custom vscode mock (tests/unit/mocks/vscode.ts) providing Position, Range, Uri, TextDocument, WorkspaceEdit, DiagnosticSeverity, and workspace stubs
• Runtime module hook (output/test/register.js) redirecting require('vscode') to the mock at runtime

Available Scripts

Developer Documentation

For detailed architecture, workflow diagrams, and implementation details, see docs/ARCHITECTURE.md.

Requirements

• VS Code 1.85.0 or higher
• Python files (.py) to validate

License

See LICENSE.md for details.

Links

• Repository
• Google Python Style Guide - Imports
• PEP 8 - Imports
• Ruff isort - known-first-party