CLASPLint

CLASP Stage 3.3 / PEP 2606 static analysis tool. Enforces naming and comment conventions beyond PEP 8 — checks variables, dictionary keys, functions, classes, comments, and log messages for standards compliance.

Features

• Variable names — group1_group2 format, all lowercase, no abbreviations, type/boolean prefixes, ≤30 chars
• Dictionary keys — PascalCase, full spelling, acronyms kept uppercase
• Function & class names — snake_case for functions, PascalCase for classes, private methods _init_X_function_
• Comment format — every physical code line requires # Capitalized sentence. comment (import/class/def exempt)
• Log messages — pre-defined string variables (6 allowed names), proper try-except chain with as variable naming, exc_info=True on error/critical/fatal, raise with from clause
• Try-Except blocks — no tuple catching, alphabetical exception ordering, Exception last, whitelist as variable names, bare raise prohibited, raise XxxError(message_error) from e required
• Docstrings — File: field-based format; Class: ATTRIBUTES/PUBLIC/PRIVATE/USAGE/WARNING; Method: Sphinx :param/:type/:return/:rtype/:raises with summary→detail→directives structure
• Encoding declaration — file header must contain # -*- coding: utf-8 -*-
• Single-line comments — each # comment is a self-contained sentence; multi-line comment blocks are forbidden
• Symbol-line exemption — pure-symbol lines (only non-letter characters) are exempt from comment requirements and must not carry comments
• Comment quality — detects weak comments that merely restate code rather than explain intent
• Comment language — all comments must be written in English
• Log quality — log message variable names must follow group1_group2 format; log message content must be in Chinese
• Docstring quality — file-level docstrings must follow CLASP field-based format (MODULE, TYPE, DESCRIPTION...); class docstrings require ATTRIBUTES/PUBLIC METHODS/PRIVATE METHODS/USAGE/WARNING sections; docstring text is checked for capitalization, punctuation, and abbreviations
• Review hints — advisory suggestions for overly long variable names (>15 chars or multi-word groups) excluded from total violation count

Installation

pip install CLASPLint

Or from source:

git clone https://github.com/thedayofthedoctor/clasplint.git
cd clasplint
pip install -e .

Quick Start

# Check a single file
CLASPLint path/to/file.py

# Check all Python files in a directory (recursive)
CLASPLint src/

# Show only summary, no per-violation output
CLASPLint --quiet src/

# Filter by violation category
CLASPLint --category variable src/

Usage

usage: CLASPLint [-h] [--version] [--no-recursive] [--quiet] [-c CATEGORY] [paths ...]

positional arguments:
  paths                 Python files or directories to check (default: current directory)

options:
  --version             show version number and exit
  --no-recursive        do not recursively check subdirectories
  --quiet, -q           suppress individual violation output; show only summary
  --category, -c {variable,dict_key,function,comment,log,docstring,tryexcept}
                        only report violations of a specific category

Example Output

$ CLASPLint tests/test_violations.py

When violations exist:

=== Code Logging Annotation Standard Proposal (CLASP) Report ===

+-------------------------+
|     Total Reports     |
+-------------------------+

From 2026-07-06 02:00:00 to 2026-07-06 02:00:00, CLASPLint totally found 13 violation(s) in
1 of 1 file(s), as follows:

    COMMENT  :    5   violation(s)
    DICT_KEY :    3   violation(s)
    FUNCTION :    2   violation(s)
    VARIABLE :    3   violation(s)

+-------------------------+
|    Full Violations    |
+-------------------------+

[Comment Violations]:
  [1] tests/test_violations.py:8:
     Line 8 lacks a required preceding comment.
       Violation Content:
         badvar = 42
  [2] tests/test_violations.py:11:
     Comment must start with '# ' (hash, space).
       Violation Content:
         #Bad_Var
  ...

When clean:

=== Code Logging Annotation Standard Proposal (CLASP) Report ===

+-------------------------+
|     Total Reports     |
+-------------------------+

From 2026-07-06 02:00:00 to 2026-07-06 02:00:00, 0 violation(s) in 11 file(s).

CLASP Stage 3.3 / PEP 2606 Rules Summary

Python Version Support

CLASPLint supports Python 3.8 through 3.14. The minimum version is 3.8 due to ast.Constant, ast.NamedExpr, and ast.get_docstring() usage.

License

GPL-3.0-only — Copyright (C) 2026 Matt Belfast Brown

CLASPLint（中文）

CLASP Stage 3.3 / PEP 2606 静态分析工具。在 PEP 8 之上强制执行命名与注释规范 —— 检查变量、字典键、函数、类、注释和日志消息是否符合标准。

功能特性

• 变量名 —— group1_group2 两段下划线格式，全部小写，禁止缩写，支持类型/布尔前缀，≤30 字符
• 字典键名 —— PascalCase 驼峰式，完整拼写，专有缩写保持大写
• 函数与类名 —— 函数 snake_case，类 PascalCase，私有方法 _init_X_function_
• 注释格式 —— 每条物理代码行前必须有 # 首字母大写英文句子并以句号结尾。（import/class/def 豁免）
• 日志消息 —— 必须预定义为字符串变量（6种允许名称），完整 try-except 链条带 as 变量命名， 错误/严重/致命日志带 exc_info=True，raise 必须用 from 链接原始异常
• 异常块 —— 禁止元组捕获，异常类型字母序排列，Exception 最后兜底，as 变量名须在白名单， 禁止裸 raise，必须 raise XxxError(message_error) from e
• 文档字符串 —— 文件级：字段式格式；类级：ATTRIBUTES/PUBLIC/PRIVATE/USAGE/WARNING； 方法级：Sphinx :param/:type/:return/:rtype/:raises，概述→详述→指令三段式
• 编码声明 —— 文件头必须包含 # -*- coding: utf-8 -*-
• 单行注释 —— 每条 # 注释为独立单行句子；禁止多行注释块
• 符号行豁免 —— 纯符号行（仅含非字母字符）免注释且不得带注释
• 注释质量 —— 检测仅复述代码而非解释意图的弱注释
• 注释语言 —— 所有注释必须使用英文
• 日志语言 —— 日志消息必须使用中文；日志变量名须符合 group1_group2 格式
• 文档字符串质量 —— 文件级 docstring 须符合 CLASP 字段式格式（MODULE/TYPE/DESCRIPTION...）；类 docstring 须含 ATTRIBUTES/PUBLIC METHODS/PRIVATE METHODS/USAGE/WARNING 段；检查文本大小写、标点与缩写
• Review 提示 —— 对过长变量名（>15 字符或多词拼接）提供建议性提示，不计入违规总数

安装

pip install CLASPLint

或从源码安装：

git clone https://github.com/thedayofthedoctor/clasplint.git
cd clasplint
pip install -e .

快速开始

# 检查单个文件
CLASPLint path/to/file.py

# 递归检查目录下所有 Python 文件
CLASPLint src/

# 仅显示摘要，不输出逐条违规
CLASPLint --quiet src/

# 按类别过滤
CLASPLint --category variable src/

命令行用法

usage: CLASPLint [-h] [--version] [--no-recursive] [--quiet] [-c CATEGORY] [paths ...]

位置参数:
  paths                 要检查的 Python 文件或目录（默认：当前目录）

可选参数:
  --version             显示版本号并退出
  --no-recursive        不递归检查子目录
  --quiet, -q           仅显示摘要，抑制逐条违规输出
  --category, -c {variable,dict_key,function,comment,log,docstring,tryexcept}
                        仅报告指定类别的违规

输出示例

$ CLASPLint tests/test_violations.py

发现违规时：

=== Code Logging Annotation Standard Proposal (CLASP) Report ===

+-------------------------+
|     Total Reports     |
+-------------------------+

From 2026-07-06 02:00:00 to 2026-07-06 02:00:00, CLASPLint totally found 13 violation(s) in
1 of 1 file(s), as follows:

    COMMENT  :    5   violation(s)
    DICT_KEY :    3   violation(s)
    FUNCTION :    2   violation(s)
    VARIABLE :    3   violation(s)

+-------------------------+
|    Full Violations    |
+-------------------------+

[Comment Violations]:
  [1] tests/test_violations.py:8:
     Line 8 lacks a required preceding comment.
       Violation Content:
         badvar = 42
  [2] tests/test_violations.py:11:
     Comment must start with '# ' (hash, space).
       Violation Content:
         #Bad_Var
  ...

无违规时：

=== Code Logging Annotation Standard Proposal (CLASP) Report ===

+-------------------------+
|     Total Reports     |
+-------------------------+

From 2026-07-06 02:00:00 to 2026-07-06 02:00:00, 0 violation(s) in 11 file(s).

CLASP Stage 3.3 / PEP 2606 规则速查

Python 版本支持

CLASPLint 支持 Python 3.8 至 3.14。最低版本为 3.8，原因在于使用了 ast.Constant、ast.NamedExpr 和 ast.get_docstring()。

许可证

GPL-3.0-only — Copyright (C) 2026 Matt Belfast Brown