CLASPLint

CLASP Stage 3.5.1 / PEP 2606 static analysis tool. Enforces naming, line, and comment conventions beyond PEP 8 — checks variables, dictionary keys, functions, classes, physical lines, 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 message_* variables, 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/:raise 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 — English remains normative; mixed-language prose is left to manual review
• 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
• Physical line length — defaults to 128 characters including indentation; configurable, minimum 100
• String construction — implicit adjacent string or f-string literals may not cross physical lines; use separate explicit += statements
• Review hints — advisory suggestions to keep variable names as short as possible without ambiguity when they exceed 15 characters or contain multi-word groups; excluded from the violation total

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; all checks still run and checking time is not reduced
CLASPLint --quiet src/

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

# Use an explicit TOML configuration
CLASPLint --config clasplint.toml src/

# Override the Python physical-line maximum
CLASPLint --line-length 120 src/

Configuration

CLASPLint uses strongly typed TOML. It loads the packaged baseline, the nearest project clasplint.toml or [tool.clasplint] table, CLASPLINT_CONFIG, --config, scalar environment variables, and command-line overrides in that order. Rule collections and logger identities are append-only. Unknown keys, invalid types, weakened minimums, and conflicting abbreviation expansions return exit code 2.

[thresholds]
line_length = 128
variable_review_length = 15
variable_error_length = 30
log_review_length = 12
termination_review_length = 20

[rules]
names_exempt = ["frameworkName"]
dictkey_exempt = ["external_key"]

[logging]
names = ["audit_logger"]
factories = ["my_logging.get_logger"]
types = ["my_logging.AuditLogger"]

Usage

usage: CLASPLint [-h] [--version] [--no-recursive] [--quiet] [-c CATEGORY]
                 [--config CONFIG] [--line-length N]
                 [--variable-review-length N] [--variable-error-length N]
                 [--log-review-length N] [--termination-review-length N] [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;
                        all checks still run, so checking time is not reduced
  --category, -c {variable,dict_key,function,comment,log,docstring,tryexcept,lines}
                        only report violations of a specific category
  --config CONFIG       use this TOML file and disable project discovery
  --line-length N       physical-line maximum (default 128; minimum 100)
  --variable-review-length N
                        variable REVIEW threshold (default/minimum 15)
  --variable-error-length N
                        variable violation threshold (default/minimum 30)
  --log-review-length N
                        log-context REVIEW threshold (default/minimum 12)
  --termination-review-length N
                        termination-comment REVIEW threshold (default/minimum 20)

Example Output

$ CLASPLint sample_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] sample_violations.py:8:
     Line 8 lacks a required preceding comment.
       Violation Content:
         badvar = 42
  [2] sample_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.5.1 / 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.5.1 / PEP 2606 静态分析工具。在 PEP 8 之上强制执行命名、物理行与注释规范 —— 检查变量、字典键、函数、类、物理行、注释和日志消息是否符合标准。

功能特性

• 变量名 —— group1_group2 两段下划线格式，全部小写，禁止缩写，支持类型/布尔前缀，≤30 字符
• 字典键名 —— PascalCase 驼峰式，完整拼写，专有缩写保持大写
• 函数与类名 —— 函数 snake_case，类 PascalCase，私有方法 _init_X_function_
• 注释格式 —— 每条物理代码行前必须有 # 首字母大写英文句子并以句号结尾。（import/class/def 豁免）
• 日志消息 —— 必须预定义为 message_* 字符串变量，完整 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/:raise，概述→详述→指令三段式
• 编码声明 —— 文件头必须包含 # -*- coding: utf-8 -*-
• 单行注释 —— 每条 # 注释为独立单行句子；禁止多行注释块
• 符号行豁免 —— 纯符号行（仅含非字母字符）免注释且不得带注释
• 注释质量 —— 检测仅复述代码而非解释意图的弱注释
• 注释语言 —— 英文仍是规范要求；混合语言文本交由人工核验
• 日志语言 —— 日志消息必须使用中文；日志变量名须符合 group1_group2 格式
• 文档字符串质量 —— 文件级 docstring 须符合 CLASP 字段式格式（MODULE/TYPE/DESCRIPTION...）；类 docstring 须含 ATTRIBUTES/PUBLIC METHODS/PRIVATE METHODS/USAGE/WARNING 段；检查文本大小写、标点与缩写
• 物理行长度 —— 默认最多 128 个字符（包含缩进），允许配置但不得低于 100
• 字符串构造 —— 普通字符串或 f-string 不得通过跨物理行相邻字面量隐式拼接；应使用独立的 += 语句
• 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/

# 使用显式 TOML 配置
CLASPLint --config clasplint.toml src/

# 覆盖 Python 物理行最大长度
CLASPLint --line-length 120 src/

配置

CLASPLint 使用强类型 TOML。优先级依次为安装包基线、最近的项目 clasplint.toml 或 [tool.clasplint]、CLASPLINT_CONFIG、--config、阈值环境变量和命令行覆盖。 规则集合与日志器身份只增不减；未知键、错误类型、低于最低值的阈值和冲突的缩写映射返回退出码 2。

TOML 结构与上方英文示例相同。

命令行用法

usage: CLASPLint [-h] [--version] [--no-recursive] [--quiet] [-c CATEGORY]
                 [--config CONFIG] [--line-length N]
                 [--variable-review-length N] [--variable-error-length N]
                 [--log-review-length N] [--termination-review-length N] [paths ...]

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

可选参数:
  --version             显示版本号并退出
  --no-recursive        不递归检查子目录
  --quiet, -q           仅显示摘要并抑制逐条违规输出；全部检查仍会执行，
                        因此不会缩短检查时间
  --category, -c {variable,dict_key,function,comment,log,docstring,tryexcept,lines}
                        仅报告指定类别的违规
  --config CONFIG       使用指定 TOML，并关闭项目配置自动发现
  --line-length N       物理行最大长度（默认 128；最低 100）
  --variable-review-length N
                        变量 REVIEW 阈值（默认/最低 15）
  --variable-error-length N
                        变量违规阈值（默认/最低 30）
  --log-review-length N
                        日志上下文 REVIEW 阈值（默认/最低 12）
  --termination-review-length N
                        异常终结注释 REVIEW 阈值（默认/最低 20）

输出示例

$ CLASPLint sample_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] sample_violations.py:8:
     Line 8 lacks a required preceding comment.
       Violation Content:
         badvar = 42
  [2] sample_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.5.1 / 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