Metadata-Version: 2.4
Name: CLASPLint
Version: 0.4.0
Summary: CLASP 3.2 / PEP 2606 Static Analysis Tool — enforces naming and comment conventions beyond PEP 8.
Author: Matt Belfast Brown
Author-email: Matt Belfast Brown <thedayofthedo@gmail.com>
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/thedayofthedoctor/clasplint
Project-URL: Repository, https://github.com/thedayofthedoctor/clasplint
Project-URL: Issues, https://github.com/thedayofthedoctor/clasplint/issues
Keywords: clasp,pep2606,linter,static-analysis,naming-convention,code-quality,python
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: license-file
Dynamic: platform
Dynamic: requires-python

# CLASPLint

[![Python](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-GPLv3-green)](./LICENSE)
[![PyPI](https://img.shields.io/badge/pypi-v0.4.0-orange)](https://pypi.org/project/CLASPLint/)

> **CLASP 3.2 / 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, proper `try-except` chains, `exc_info=True` on errors
- **Docstrings** — presence check for all functions and classes; Sphinx `:param/:type/:return` format enforcement for methods with detailed description requirement
- **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

```bash
pip install CLASPLint
```

Or from source:

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

## Quick Start

```bash
# 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}
                        only report violations of a specific category
```

## Example Output

```bash
$ 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 3.2 / PEP 2606 Rules Summary

| Category     | Rule                                                                                        |
|--------------|---------------------------------------------------------------------------------------------|
| Variable     | `group1_group2`, one underscore, all lowercase, no abbreviations, ≤30 chars                 |
| Boolean      | `is_` or `has_` prefix (mandatory for bool-annotated and bool-literal variables)            |
| Constant     | Lowercase group1_group2 format (ALL_CAPS prohibited)                                        |
| Dict Key     | PascalCase, full spelling, acronyms uppercase (GPS, UTM, XML, etc.)                         |
| Class        | PascalCase                                                                                  |
| Function     | snake_case, specific verb, ≤30 chars                                                        |
| Method       | Public: short snake_case; Private: `_init_X_function_` ≤30 chars                            |
| Comment      | Every physical line: `# Capitalized sentence ending with period.` (import/class/def exempt) |
| Control Flow | Body first line must have a preceding comment (if/for/while)                                |
| Log          | Messages as pre-defined variables (5 allowed names), proper `try-except` chain, `exc_info=True` |
| Docstring    | File: field-based format; Class: ATTRIBUTES/PUBLIC/PRIVATE/USAGE/WARNING; Method: Sphinx `:param/:type/:return` |
| Encoding     | `# -*- coding: utf-8 -*-` required at file top (line 1 or 2 after shebang)                  |
| Symbol Line  | Pure-symbol lines (no letters) are comment-exempt and must not carry comments               |
| Multi-line   | Each comment must be a single self-contained line; blocks are forbidden                     |
| Weak Comment | Comments must explain intent, not paraphrase conditions (no "Check if...")                  |
| Comment Lang | All comments must be in English (ASCII only)                                                |
| Log Lang     | Log messages must be in Chinese                                                             |
| Log Variable | Log message variables limited to: message_info/debug/warning/error/fatal                    |
| Review       | Advisory hints for long or multi-word variable names (excluded from total count)            |

## 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](./LICENSE) — Copyright (C) 2026 Matt Belfast Brown

---

<!-- TODO: add badges, CI status, coverage, etc. -->

---

# CLASPLint（中文）

[![Python](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-GPLv3-green)](./LICENSE)
[![PyPI](https://img.shields.io/badge/pypi-v0.4.0-orange)](https://pypi.org/project/CLASPLint/)

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

---

## 功能特性

- **变量名** —— `group1_group2` 两段下划线格式，全部小写，禁止缩写，支持类型/布尔前缀，≤30 字符
- **字典键名** —— PascalCase 驼峰式，完整拼写，专有缩写保持大写
- **函数与类名** —— 函数 snake_case，类 PascalCase，私有方法 `_init_X_function_`
- **注释格式** —— 每条物理代码行前必须有 `# 首字母大写英文句子并以句号结尾。`（import/class/def 豁免）
- **日志消息** —— 必须预定义为字符串变量，完整的 `try-except` 链条，错误日志带 `exc_info=True`
- **文档字符串** —— 函数和类必须存在；方法需遵循 Sphinx `:param/:type/:return` 格式，并包含详细逻辑描述段落
- **编码声明** —— 文件头必须包含 `# -*- coding: utf-8 -*-`
- **单行注释** —— 每条 `#` 注释为独立单行句子；禁止多行注释块
- **符号行豁免** —— 纯符号行（仅含非字母字符）免注释且不得带注释
- **注释质量** —— 检测仅复述代码而非解释意图的弱注释
- **注释语言** —— 所有注释必须使用英文
- **日志语言** —— 日志消息必须使用中文；日志变量名须符合 `group1_group2` 格式
- **文档字符串质量** —— 文件级 docstring 须符合 CLASP 字段式格式（MODULE/TYPE/DESCRIPTION...）；类 docstring 须含 ATTRIBUTES/PUBLIC METHODS/PRIVATE METHODS/USAGE/WARNING 段；检查文本大小写、标点与缩写
- **Review 提示** —— 对过长变量名（>15 字符或多词拼接）提供建议性提示，不计入违规总数

## 安装

```bash
pip install CLASPLint
```

或从源码安装：

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

## 快速开始

```bash
# 检查单个文件
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}
                        仅报告指定类别的违规
```

## 输出示例

```bash
$ 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 3.2 / PEP 2606 规则速查

| 类别    | 规则                                                                      |
|-------|-------------------------------------------------------------------------|
| 变量    | `group1_group2`，有且仅有一个下划线，全部小写，禁止缩写，≤30 字符                              |
| 布尔值   | `is_` 或 `has_` 前缀（bool 注解和 bool 字面量赋值强制）                                  |
| 常量    | 小写 group1_group2 格式（禁止 ALL_CAPS）                                           |
| 字典键   | PascalCase 驼峰式，完整拼写，专有缩写大写（GPS、UTM、XML 等）                               |
| 类名    | PascalCase                                                              |
| 函数名   | snake_case，使用具体动词，≤30 字符                                                |
| 方法    | 公共：简短 snake_case；私有：`_init_X_function_` ≤30 字符                          |
| 注释    | 每条物理行：`# Capitalized sentence ending with period.`（import/class/def 豁免） |
| 控制流   | 分支/循环体首行必须拥有前置注释（if/for/while）                                          |
| 日志    | 消息预定义为变量（5 种允许名称），完整 `try-except` 日志链，`exc_info=True`                   |
| 文档字符串 | 文件级：字段式格式；类级：ATTRIBUTES/PUBLIC/PRIVATE/USAGE/WARNING；方法级：Sphinx `:param/:type/:return` |
| 编码声明  | 文件顶部须有 `# -*- coding: utf-8 -*-`（第1行或shebang后第2行）                       |
| 符号行   | 纯符号行（无字母）免注释且禁止带注释                                                      |
| 单行注释  | 每条注释为独立单行句子；禁止多行注释块                                                     |
| 弱注释   | 注释须解释意图，不得仅复述代码（禁止 "Check if..."）                                       |
| 注释语言  | 所有注释须使用英文（仅 ASCII 字符）                                                   |
| 日志语言  | 日志消息须使用中文                                                               |
| 日志变量  | 日志变量名限定为：message_info/debug/warning/error/fatal                            |
| Review  | 对过长或多词拼接变量名的建议性提示（不计入违规总数）                                             |

## Python 版本支持

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

## 许可证

[GPL-3.0-only](./LICENSE) — Copyright (C) 2026 Matt Belfast Brown
