CSpell Python Dictionary

CSpell Python Dictionary is a pre-built dictionary extension for cspell (Code Spell Checker) that provides comprehensive spell checking support for Python source code files. It contains specialized Python language dictionaries with keywords, built-in functions, and common Python programming terms, along with sophisticated pattern matching for Python-specific syntax.

Package Information

• Package Name: @cspell/dict-python
• Package Type: npm
• Language: JSON/Configuration
• Installation: npm install -g @cspell/dict-python
• Requirements: cspell >= 5.5.0

Core Imports

The package exports a cspell extension configuration that can be imported directly:

// Import as default in cspell.json
{
  "import": ["@cspell/dict-python"]
}

// Import via specific paths in cspell.json
{
  "import": ["@cspell/dict-python/cspell"]
}

// Import via explicit file path in cspell.json
{
  "import": ["@cspell/dict-python/cspell-ext.json"]
}

Basic Usage

Global Installation and Registration

# Install globally
npm install -g @cspell/dict-python

# Register with cspell
cspell link add @cspell/dict-python

Project-Specific Integration

Add to your project's cspell.json configuration:

{
  "import": ["@cspell/dict-python/cspell-ext.json"],
  "files": ["src/**/*.py"]
}

Manual Uninstallation

# Remove from cspell
cspell link remove @cspell/dict-python

Architecture

The package provides a comprehensive Python dictionary system through several key components:

• Dictionary Files: Two compressed dictionary files (python.txt.gz, python-common.txt.gz) containing Python keywords and common terms
• Configuration: cspell extension configuration (cspell-ext.json) with language-specific settings
• Pattern Recognition: Advanced regex patterns for Python string literals, comments, and syntax
• Source Files: Text files in src/python/ and src/common/ directories used to build dictionaries
• Build System: npm scripts that compile dictionaries from source text files using cspell-tools-cli

Capabilities

Dictionary Configuration

The main configuration that defines how cspell should handle Python files.

{
  "id": "python",
  "version": "0.2", 
  "readonly": true,
  "name": "Python Dictionary",
  "description": "Python Keyword Dictionary",
  "dictionaryDefinitions": [
    {
      "name": "python",
      "path": "./python.txt.gz",
      "description": "Python Dictionary"
    },
    {
      "name": "python-common", 
      "path": "./python-common.txt.gz",
      "description": "Python Common Terms Dictionary"
    }
  ],
  "dictionaries": [],
  "languageSettings": [
    {
      "languageId": "python",
      "dictionaries": ["python", "python-common"],
      "ignoreRegExpList": ["ignore_string_literal_prefix"],
      "patterns": [...]
    }
  ]
}

Dictionary Definitions

The configuration defines two main dictionaries with their file paths and descriptions.

"dictionaryDefinitions": [
  {
    "name": "python",
    "path": "./python.txt.gz",
    "description": "Python Dictionary"
  },
  {
    "name": "python-common",
    "path": "./python-common.txt.gz",
    "description": "Python Common Terms Dictionary"
  }
]

Available Dictionaries:

• python: Core Python keywords, built-in functions, magic methods (e.g., __init__, __call__, isinstance, enumerate)
• python-common: Common Python programming terms and framework-specific vocabulary (e.g., pythonic, django, numpy, matplotlib)

Language Settings

Language-specific configuration that applies dictionaries and patterns to Python files.

"languageSettings": [
  {
    "languageId": "python",
    "dictionaries": ["python", "python-common"],
    "ignoreRegExpList": ["ignore_string_literal_prefix"],
    "patterns": [...] // See Pattern Recognition section
  }
]

Pattern Recognition

Advanced regex patterns for handling Python-specific syntax elements.

"patterns": [
  {
    "name": "ignore_string_literal_prefix",
    "pattern": "/\\b(?:rf|fr|f|r|u|ur|b|br)'/gi"
  },
  {
    "name": "string_binary",
    "pattern": "/\\bbr?(['\"]).*?\\1/gi"
  },
  {
    "name": "string_raw",
    "pattern": "/\\bu?r(['\"]).*?\\1/gi"
  },
  {
    "name": "string-multi-line",
    "pattern": "/(\"\"\"|''')[^\\1]*?\\1/g"
  },
  {
    "name": "string-single-line",
    "pattern": "/((?<!\\\\)(?:'|\"))(?!\\1).*?(?<!\\1)(?<!\\\\)\\1(?!\\1)/g"
  },
  {
    "name": "comment-single-line",
    "pattern": "/#.*/g"
  },
  {
    "name": "comment-multi-line",
    "pattern": "/(\"\"\"|''')[^\\1]*?\\1/g"
  },
  {
    "name": "strings",
    "description": "Matches all strings in a Python File.",
    "pattern": [
      "/((?<!\\\\)(?:'|\"))(?!\\1).*?(?<!\\1)(?<!\\\\)\\1(?!\\1)/g",
      "/(\"\"\"|''')[^\\1]*?\\1/g"
    ]
  },
  {
    "name": "comments",
    "description": "Matches all comments in a Python File.",
    "pattern": [
      "/#.*/g",
      "/(\"\"\"|''')[^\\1]*?\\1/g"
    ]
  }
]

Build System

npm scripts for compiling dictionary files from source text files.

"scripts": {
  "build": "yarn run build-python && yarn run build-common",
  "build-python": "cspell-tools-cli compile \"src/python/*.txt\" \"src/additional_words.txt\" --split --keep-raw-case --merge python -o .",
  "build-common": "cspell-tools-cli compile \"src/common/*.txt\" --keep-raw-case --merge python-common -o .",
  "prepare": "yarn run build"
}

Build Process:

• build: Main command that compiles both dictionaries sequentially
• build-python: Compiles python.txt.gz from source files in src/python/ plus src/additional_words.txt
• build-common: Compiles python-common.txt.gz from source files in src/common/
• prepare: Automatically runs build before publishing

Test System

npm scripts for validating dictionary effectiveness against sample files.

"scripts": {
  "test": "yarn run test-dictionary && yarn run test-samples",
  "test-dictionary": "cspell -v -c ./cspell-ext.json --local=en --languageId=python \"src/python/py*.txt\"",
  "test-samples": "cspell -v -c ./cspell-ext.json \"samples/**/*.py\""
}

Test Process:

• test: Runs both dictionary and sample tests
• test-dictionary: Validates dictionary against source Python keyword files
• test-samples: Tests dictionary against sample Python files in samples/ directory

Maintenance Scripts

Additional scripts for maintaining the dictionary content:

"scripts": {
  "update-python-lib": "./scripts/fetch-python.sh",
  "prepublishOnly": "echo pre-publish"
}

Maintenance Process:

• update-python-lib: Updates Python standard library terms using the fetch script
• prepublishOnly: Pre-publish validation hook

Package Exports

The package provides multiple export paths for flexible integration:

"exports": {
  ".": "./cspell-ext.json",
  "./cspell": "./cspell-ext.json",
  "./cspell-ext.json": "./cspell-ext.json"
}

All exports point to the same configuration file (cspell-ext.json) which contains the complete dictionary setup.

Package Files

The published package includes only the essential files for distribution:

"files": [
  "python.txt.gz",
  "python-common.txt.gz", 
  "cspell-ext.json"
]

These compressed dictionary files and configuration are all that's needed for cspell integration.

Dictionary Content

Core Python Dictionary

Contains essential Python language elements:

• Magic Methods: __init__, __call__, __str__, __repr__, __len__, etc.
• Built-in Functions: len, str, int, float, list, dict, tuple, set, etc.
• Keywords: def, class, import, from, if, else, elif, for, while, etc.
• Exceptions: Exception, ValueError, TypeError, KeyError, etc.

Common Terms Dictionary

Contains frequently used Python programming vocabulary:

• Framework Terms: Django, Flask, FastAPI related terminology
• Library Names: numpy, pandas, matplotlib, requests, etc.
• Programming Concepts: pythonic, docstring, unittest, pytest
• Technical Terms: middleware, serialization, decorator, generator

Source File Structure

The dictionary is built from text source files organized in a specific directory structure:

"src/": {
  "python/": {
    "python.txt": "Core Python keywords and built-ins",
    "python-lib.txt": "Python standard library terms"
  },
  "common/": {
    "extra.txt": "Additional common programming terms"
  },
  "additional_words.txt": "Supplementary words for the Python dictionary"
}

Source Files:

• src/python/python.txt: Core Python language keywords, built-in functions, and magic methods
• src/python/python-lib.txt: Standard library module names and common functions
• src/common/extra.txt: Framework names, common programming terminology
• src/additional_words.txt: Additional specialized terms for Python development

Error Handling

The package handles common integration issues:

• Missing cspell: Package requires cspell >= 5.5.0 to function properly
• Build Failures: Dictionary compilation may fail if source files are corrupted
• Configuration Errors: Invalid cspell.json syntax will prevent proper loading

Common error patterns and solutions:

# If dictionaries are not found
npm run build

# If global registration fails
cspell link remove @cspell/dict-python
cspell link add @cspell/dict-python

# If local import fails, check cspell.json syntax
{
  "import": ["@cspell/dict-python/cspell-ext.json"]
}