galaxy-linting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Persona: You are a senior Galaxy developer specializing in code quality, style enforcement, and CI compliance.

Arguments:

$ARGUMENTS - Optional task specifier: "check", "fix", "python", "client", "mypy", "full" Examples: "", "check", "fix", "python", "mypy"

Parse $ARGUMENTS to determine which guidance to provide.

角色定位：您是一位专注于代码质量、风格规范与CI合规性的资深Galaxy开发者。

参数：

$ARGUMENTS - 可选任务指定符："check"、"fix"、"python"、"client"、"mypy"、"full" 示例：""、"check"、"fix"、"python"、"mypy"

解析$ARGUMENTS以确定需要提供的指导内容。

Quick Reference: Galaxy Linting & Formatting

快速参考：Galaxy代码检查与格式化

Galaxy uses multiple linting tools enforced through CI:

Python: ruff (lint + format), black, isort, flake8, darker (incremental formatting), mypy (type checking)
Client: ESLint, Prettier

CI commands:

tox -e lint

tox -e format

tox -e mypy

tox -e lint_docstring_include_list

Galaxy通过CI强制执行多种代码检查工具：

Python： ruff（检查+格式化）、black、isort、flake8、darker（增量格式化）、mypy（类型校验）
客户端： ESLint、Prettier

CI命令：

tox -e lint

、

tox -e format

、

tox -e mypy

、

tox -e lint_docstring_include_list

Tools Overview

工具概述

Tool	Purpose	Config File	Check Command	Fix Command
ruff	Fast Python linter + formatter	`pyproject.toml`	`ruff check .`	`ruff check --fix .`
black	Python code formatter	`pyproject.toml`	`black --check .`	`black .`
isort	Python import sorter	`pyproject.toml`	`isort --check .`	`isort .`
flake8	Python linter (legacy)	`.flake8`	`flake8 .`	N/A (manual)
darker	Incremental formatter	N/A	N/A	`make diff-format`
autoflake	Remove unused imports	N/A	N/A	`make remove-unused-imports`
pyupgrade	Modernize Python syntax	N/A	N/A	`make pyupgrade`
mypy	Type checker	`pyproject.toml`	`tox -e mypy`	N/A (manual)
ESLint	JavaScript/TypeScript linter	`client/.eslintrc.js`	`make client-lint`	`make client-format`
Prettier	JS/TS/CSS formatter	`client/.prettierrc.yml`	`make client-lint`	`make client-format`

工具	用途	配置文件	检查命令	修复命令
ruff	快速Python代码检查器+格式化工具	`pyproject.toml`	`ruff check .`	`ruff check --fix .`
black	Python代码格式化工具	`pyproject.toml`	`black --check .`	`black .`
isort	Python导入语句排序工具	`pyproject.toml`	`isort --check .`	`isort .`
flake8	传统Python代码检查器（遗留工具）	`.flake8`	`flake8 .`	无（需手动修复）
darker	增量格式化工具	无	无	`make diff-format`
autoflake	移除未使用的导入语句	无	无	`make remove-unused-imports`
pyupgrade	升级Python语法至现代风格	无	无	`make pyupgrade`
mypy	类型校验工具	`pyproject.toml`	`tox -e mypy`	无（需手动修复）
ESLint	JavaScript/TypeScript代码检查器	`client/.eslintrc.js`	`make client-lint`	`make client-format`
Prettier	JS/TS/CSS格式化工具	`client/.prettierrc.yml`	`make client-lint`	`make client-format`

If $ARGUMENTS is empty or "check": Quick Lint Check

当$ARGUMENTS为空或"check"时：快速代码检查

Run the fastest feedback loop to catch most issues:

bash

undefined

运行最快的反馈循环以捕获大多数问题：

bash

undefined

1. Check formatting (fast - shows what would change)

1. 检查格式（快速 - 仅报告需修改的内容）

tox -e format

2. Check linting (catches style violations)

2. 检查代码规范（捕获风格违规问题）

tox -e lint


**What these check:**
- **`tox -e format`**: Runs black, isort checks (no changes, just reports)
- **`tox -e lint`**: Runs ruff and flake8 (reports violations)

**If you see errors**, use `/galaxy-linting fix` to auto-fix, or `/galaxy-linting python` for detailed guidance.

**Note:** These commands run in tox environments, which may take ~10-20 seconds to set up on first run. Subsequent runs are faster.

---

tox -e lint


**检查内容说明：**
- **`tox -e format`**：执行black、isort检查（不修改代码，仅报告问题）
- **`tox -e lint`**：执行ruff和flake8检查（报告违规内容）

**若发现错误**，使用`/galaxy-linting fix`进行自动修复，或使用`/galaxy-linting python`获取详细指导。

**注意：** 这些命令在tox环境中运行，首次启动可能需要10-20秒进行环境初始化，后续运行会更快。

---

If $ARGUMENTS is "fix": Auto-Fix Formatting

当$ARGUMENTS为"fix"时：自动修复格式问题

Galaxy provides multiple ways to auto-fix formatting issues.

Galaxy提供多种方式自动修复格式问题。

Recommended: Incremental Formatting (Faster)

推荐方式：增量格式化（更快）

Fix only changed lines using darker (via Makefile):

bash

undefined

使用darker（通过Makefile）仅修复已修改的代码行：

bash

undefined

Fix formatting for uncommitted changes only

仅修复未提交更改的代码格式

make diff-format


**What it does:**
- Runs black and isort only on lines you modified
- Compares against `origin/dev` branch
- Much faster than formatting entire codebase
- Recommended for daily development

make diff-format


**功能说明：**
- 仅对您修改过的代码行执行black和isort格式化
- 与`origin/dev`分支进行对比
- 比格式化整个代码库快得多
- 推荐日常开发使用

Full Formatting (Comprehensive)

全量格式化（全面覆盖）

Format entire codebase:

bash

undefined

格式化整个代码库：

bash

undefined

Format all Python files

格式化所有Python文件

make format


**What it does:**
- Runs black on all Python files
- Runs isort on all Python imports
- Takes longer but ensures full compliance
- Recommended before final commit

make format


**功能说明：**
- 对所有Python文件执行black格式化
- 对所有导入语句执行isort排序
- 耗时较长但能确保完全合规
- 推荐在最终提交前使用

Specific Fixes

特定修复操作

Fix ruff auto-fixable issues:

bash

ruff check --fix .

Remove unused imports:

bash

make remove-unused-imports

Modernize Python syntax (pyupgrade):

bash

make pyupgrade

Converts old-style Python patterns to Python 3.8/3.9 idioms (e.g.,

typing.List

→

list

, adds walrus operators where appropriate). Skips vendored/generated paths.

Fix client-side formatting:

bash

make client-format

修复ruff可自动修复的问题：

bash

ruff check --fix .

移除未使用的导入语句：

bash

make remove-unused-imports

升级Python语法至现代风格（pyupgrade）：

bash

make pyupgrade

将旧风格Python语法转换为Python 3.8/3.9规范（例如：

typing.List

→

list

，在合适的地方添加海象运算符）。会跳过第三方依赖或自动生成的代码路径。

修复客户端代码格式：

bash

make client-format

Workflow Recommendation

工作流推荐

bash

undefined

bash

undefined

During development (fast):

开发过程中（快速）：

make diff-format

Before committing (thorough):

提交前（彻底检查）：

make format tox -e lint # Verify no remaining issues

---

make format tox -e lint # 验证是否存在剩余问题

---

If $ARGUMENTS is "python": Python Linting Details

当$ARGUMENTS为"python"时：Python代码检查详情

Galaxy's Python linting stack consists of multiple tools, each with a specific purpose.

Galaxy的Python代码检查栈由多个工具组成，每个工具都有特定用途。

Ruff (Primary Linter)

Ruff（主要代码检查器）

Fast, modern Python linter that replaces many tools.

Check for issues:

bash

ruff check .

Auto-fix issues:

bash

ruff check --fix .

Configuration:

pyproject.toml

under

[tool.ruff]

and

[tool.ruff.lint]

Key rule categories:

F: Pyflakes errors (undefined names, unused imports)
E, W: PEP 8 style violations
I: Import sorting (isort-compatible)
N: Naming conventions
UP: Modernization (e.g., use
```
list[int]
```
instead of
```
List[int]
```
)
B: Bugbear (likely bugs)
A: Avoid shadowing builtins

Common errors and fixes:

```
F401
```
- Unused import → Remove import or use
```
# noqa: F401
```
```
F841
```
- Unused variable → Remove or rename to
```
_
```
```
E501
```
- Line too long (>120 chars) → Break into multiple lines
```
UP
```
- Use modern syntax → Let ruff auto-fix with
```
--fix
```

快速、现代的Python代码检查器，可替代多种传统工具。

检查问题：

bash

ruff check .

自动修复问题：

bash

ruff check --fix .

配置文件：

pyproject.toml

中的

[tool.ruff]

和

[tool.ruff.lint]

章节

核心规则类别：

F：Pyflakes错误（未定义名称、未使用的导入）
E、W：PEP 8风格违规
I：导入语句排序（与isort兼容）
N：命名规范
UP：语法现代化（例如：使用
```
list[int]
```
替代
```
List[int]
```
）
B：Bugbear规则（潜在bug）
A：避免遮蔽内置函数

常见错误与修复方法：

```
F401
```
- 未使用的导入 → 移除导入语句或添加
```
# noqa: F401
```
注释
```
F841
```
- 未使用的变量 → 移除变量或重命名为
```
_
```
```
E501
```
- 代码行过长（>120字符） → 拆分为多行
```
UP
```
类错误 - 使用现代语法 → 运行
```
ruff check --fix
```
自动修复

Black (Code Formatter)

Black（代码格式化工具）

Opinionated code formatter - ensures consistent style.

Check what would change:

bash

black --check .

Format files:

bash

black .

Configuration:

pyproject.toml

under

[tool.black]

Line length: 120 characters
Target version: Python 3.9+

Common scenarios:

"black would reformat" error in CI → Run
```
black .
```
locally
String formatting → Black enforces double quotes
Multiline expressions → Black has strong opinions on line breaks

具有强约束的代码格式化工具 - 确保代码风格一致。

检查需修改的内容：

bash

black --check .

格式化文件：

bash

black .

配置文件：

pyproject.toml

中的

[tool.black]

章节

行长度：120字符
目标Python版本：3.9+

常见场景：

CI中出现"black would reformat"错误 → 本地运行
```
black .
```
字符串格式化 → Black强制使用双引号
多行表达式 → Black对换行有严格要求

isort (Import Sorter)

isort（导入语句排序工具）

Sorts and organizes imports into groups.

Check import order:

bash

isort --check .

Fix import order:

bash

isort .

Configuration:

pyproject.toml

under

[tool.isort]

Profile: "black" (compatible with black formatting)
Line length: 120

Import groups (in order):

Standard library imports
Third-party imports
Local application imports

Example:

python

undefined

将导入语句排序并分组。

检查导入顺序：

bash

isort --check .

修复导入顺序：

bash

isort .

配置文件：

pyproject.toml

中的

[tool.isort]

章节

配置文件："black"（与Black格式化兼容）
行长度：120

导入分组顺序：

标准库导入
第三方库导入
本地应用导入

示例：

python

undefined

Standard library

标准库

import os from typing import Optional

Third-party

第三方库

from fastapi import APIRouter from pydantic import BaseModel

Local

本地模块

from galaxy.managers.workflows import WorkflowsManager from galaxy.schema.schema import WorkflowSummary

undefined

from galaxy.managers.workflows import WorkflowsManager from galaxy.schema.schema import WorkflowSummary

undefined

Flake8 (Legacy Linter)

Flake8（遗留代码检查器）

Traditional Python linter - still used alongside ruff.

Run flake8:

bash

flake8 .

Configuration:

.flake8

file in repository root

Note: Ruff covers most flake8 checks. Galaxy maintains flake8 for specific rules not yet in ruff.

传统Python代码检查器 - 仍与ruff配合使用。

运行flake8：

bash

flake8 .

配置文件： 仓库根目录下的

.flake8

文件

注意： ruff已覆盖大多数flake8检查规则。Galaxy保留flake8用于处理ruff尚未支持的特定规则。

Darker (Incremental Formatter)

Darker（增量格式化工具）

Applies black/isort only to changed lines.

Format changed code:

bash

make diff-format

How it works:

Compares working tree to
```
origin/dev
```
Runs black and isort only on modified lines
Much faster than full formatting
Ideal for daily development

Use when:

Working on large files with many unchanged lines
Want fast formatting feedback
Developing features incrementally

仅对已修改的代码行应用black/isort格式化。

格式化已修改的代码：

bash

make diff-format

工作原理：

将工作区与
```
origin/dev
```
分支对比
仅对修改过的代码行执行black和isort格式化
比全量格式化快得多
适合日常开发使用

适用场景：

处理包含大量未修改代码行的大文件
想要快速获取格式修复反馈
增量开发功能

CI Integration

CI集成

GitHub Actions runs these checks:

```
.github/workflows/lint.yaml
```
defines CI linting pipeline

Four tox environments:

format

lint

mypy

lint_docstring_include_list

To match CI locally:

bash

tox -e format  # Check formatting
tox -e lint    # Check linting

GitHub Actions会执行以下检查：

```
.github/workflows/lint.yaml
```
定义了CI代码检查流水线

四个tox环境：

format

、

lint

、

mypy

、

lint_docstring_include_list

本地模拟CI检查：

bash

tox -e format  # 检查格式合规性
tox -e lint    # 检查代码规范

Configuration Files

配置文件

Python linting configuration:

```
pyproject.toml
```
- ruff, black, isort, mypy config
```
.flake8
```
- flake8 rules and exclusions
```
tox.ini
```
- tox environment definitions

Read these files to understand specific rules:

bash

undefined

Python代码检查配置文件：

```
pyproject.toml
```
- ruff、black、isort、mypy的配置
```
.flake8
```
- flake8的规则与排除项
```
tox.ini
```
- tox环境定义

查看这些文件以了解具体规则：

bash

undefined

View ruff config

查看ruff配置

grep -A 20 '[tool.ruff]' pyproject.toml

View black config

查看black配置

grep -A 10 '[tool.black]' pyproject.toml

View flake8 config

查看flake8配置

cat .flake8

---

cat .flake8

---

If $ARGUMENTS is "client": Client-Side Linting

当$ARGUMENTS为"client"时：客户端代码检查

Galaxy's client-side code (Vue.js, TypeScript) uses ESLint and Prettier.

Galaxy的客户端代码（Vue.js、TypeScript）使用ESLint和Prettier。

Prerequisites

前置条件

Ensure Node.js dependencies are installed:

bash

make client-node-deps

This installs ESLint, Prettier, and related packages in

client/node_modules/

确保已安装Node.js依赖：

bash

make client-node-deps

该命令会在

client/node_modules/

目录下安装ESLint、Prettier及相关依赖包。

ESLint (JavaScript/TypeScript Linter)

ESLint（JavaScript/TypeScript代码检查器）

Check for linting issues:

bash

make client-lint

Configuration:

client/.eslintrc.js

Rules enforced:

Vue.js best practices
TypeScript type safety
Unused variables
Console statements (warnings)
Naming conventions

Common issues:

Unused variables → Remove or prefix with
```
_
```
Missing types → Add TypeScript type annotations
Vue template issues → Check component syntax
Console.log statements → Remove or justify with comments

检查代码规范问题：

bash

make client-lint

配置文件：

client/.eslintrc.js

强制执行的规则：

Vue.js最佳实践
TypeScript类型安全
未使用的变量
Console语句（警告）
命名规范

常见问题：

未使用的变量 → 移除变量或添加
```
_
```
前缀
缺失类型注解 → 添加TypeScript类型注解
Vue模板问题 → 检查组件语法
Console.log语句 → 移除或添加注释说明

Prettier (Code Formatter)

Prettier（代码格式化工具）

Format client code:

bash

make client-format

Configuration:

client/.prettierrc.yml

Formats:

JavaScript/TypeScript files
Vue single-file components
CSS/SCSS files
JSON files

Integration with ESLint:

Prettier handles formatting (indentation, quotes, line breaks)
ESLint handles code quality (unused vars, type safety)
ESLint config includes
```
prettier
```
plugin to avoid conflicts

格式化客户端代码：

bash

make client-format

配置文件：

client/.prettierrc.yml

支持格式化的文件类型：

JavaScript/TypeScript文件
Vue单文件组件
CSS/SCSS文件
JSON文件

与ESLint的集成：

Prettier负责格式处理（缩进、引号、换行）
ESLint负责代码质量检查（未使用变量、类型安全）
ESLint配置中包含
```
prettier
```
插件以避免规则冲突

Granular Makefile Targets

细粒度Makefile目标

Galaxy's Makefile provides fine-grained control over client linting:

Run only ESLint (no Prettier check):

bash

make client-eslint

Run only Prettier check (no ESLint):

bash

make client-format-check

Auto-fix ESLint errors with --fix (no Prettier):

bash

make client-lint-autofix

Pre-commit hook linting (for specific file paths):

bash

make client-eslint-precommit

This is used by Git hooks and operates on specific file paths rather than glob patterns.

Important distinctions:

make client-lint

make client-eslint

make client-format-check

(runs both tools)

make client-format

make client-lint-autofix

+ Prettier write (auto-fixes everything)

Galaxy的Makefile提供了对客户端代码检查的细粒度控制：

仅运行ESLint检查（不包含Prettier检查）：

bash

make client-eslint

仅运行Prettier检查（不包含ESLint）：

bash

make client-format-check

使用--fix自动修复ESLint错误（不包含Prettier）：

bash

make client-lint-autofix

预提交钩子检查（针对特定文件路径）：

bash

make client-eslint-precommit

该命令由Git钩子调用，仅对特定文件路径进行检查，而非全局匹配。

重要区别：

make client-lint

make client-eslint

make client-format-check

（运行两个工具）

```
make client-format
```
=
```
make client-lint-autofix
```
+ Prettier写入操作（自动修复所有问题）

Manual Commands

手动命令

Run ESLint directly:

bash

cd client
npm run eslint

Run Prettier directly:

bash

cd client
npm run prettier:check  # Check
npm run prettier:write  # Fix

直接运行ESLint：

bash

cd client
npm run eslint

直接运行Prettier：

bash

cd client
npm run prettier:check  # 检查格式
npm run prettier:write  # 修复格式

Client Lint Workflow

客户端代码检查工作流

bash

undefined

bash

undefined

1. Install dependencies (if needed)

1. 安装依赖（若未安装）

make client-node-deps

2. Check for issues

2. 检查问题

make client-lint

3. Auto-fix formatting

3. 自动修复格式

make client-format

4. Manually fix remaining ESLint issues

4. 手动修复剩余ESLint问题

(Edit files based on lint output)

（根据检查输出修改文件）

5. Verify fixed

5. 验证修复结果

make client-lint

---

make client-lint

---

If $ARGUMENTS is "mypy": Type Checking

当$ARGUMENTS为"mypy"时：类型校验

Galaxy uses mypy for static type checking with strict mode enabled.

Galaxy使用mypy进行静态类型校验，并启用了严格模式。

Running Type Checks

执行类型检查

Check types across codebase:

bash

tox -e mypy

Check specific file or directory:

bash

mypy lib/galaxy/managers/workflows.py
mypy lib/galaxy/schema/

Configuration:

pyproject.toml

under

[tool.mypy]

Strict mode enabled:

```
disallow_untyped_defs
```
- All functions must have type hints
```
disallow_any_generics
```
- Must specify generic types (e.g.,
```
List[str]
```
not
```
List
```
)
```
warn_return_any
```
- Warn on returning
```
Any
```
```
warn_unused_ignores
```
- Warn on unnecessary
```
# type: ignore
```
comments

检查整个代码库的类型：

bash

tox -e mypy

检查特定文件或目录：

bash

mypy lib/galaxy/managers/workflows.py
mypy lib/galaxy/schema/

配置文件：

pyproject.toml

中的

[tool.mypy]

章节

已启用的严格模式规则：

```
disallow_untyped_defs
```
- 所有函数必须包含类型注解
```
disallow_any_generics
```
- 必须指定泛型类型（例如：
```
List[str]
```
而非
```
List
```
）
```
warn_return_any
```
- 返回
```
Any
```
类型时发出警告
```
warn_unused_ignores
```
- 对不必要的
```
# type: ignore
```
注释发出警告

Common Type Errors

常见类型错误

Error: "Function is missing a type annotation"

python

undefined

错误："Function is missing a type annotation"

python

undefined

Bad

错误示例

def process_workflow(workflow_id): ...

Good

正确示例

def process_workflow(workflow_id: int) -> dict: ...


**Error: "Need type annotation for variable"**
```python

def process_workflow(workflow_id: int) -> dict: ...


**错误："Need type annotation for variable"**
```python

Bad

错误示例

workflows = []

Good

正确示例

workflows: List[Workflow] = []


**Error: "Incompatible return value type"**
```python

workflows: List[Workflow] = []


**错误："Incompatible return value type"**
```python

Bad

错误示例

def get_workflow() -> Workflow: return None # Error: None is not Workflow

def get_workflow() -> Workflow: return None # 错误：None不是Workflow类型

Good

正确示例

from typing import Optional

def get_workflow() -> Optional[Workflow]: return None # OK: Optional[Workflow] allows None


**Error: "Incompatible types in assignment"**
```python

from typing import Optional

def get_workflow() -> Optional[Workflow]: return None # 正确：Optional[Workflow]允许返回None


**错误："Incompatible types in assignment"**
```python

Bad

错误示例

workflow_id: int = "123" # Error: str is not int

workflow_id: int = "123" # 错误：str类型无法赋值给int类型

Good

正确示例

workflow_id: int = 123


**Error: "Cannot determine type of variable"**
```python

workflow_id: int = 123


**错误："Cannot determine type of variable"**
```python

Bad (mypy can't infer type)

错误示例（mypy无法推断类型）

result = get_complex_data()

Good (explicit annotation)

正确示例（显式类型注解）

result: Dict[str, Any] = get_complex_data()

undefined

result: Dict[str, Any] = get_complex_data()

undefined

Type Ignoring (Use Sparingly)

忽略类型检查（谨慎使用）

When mypy is wrong or you're working with untyped libraries:

python

undefined

当mypy判断错误或处理无类型注解的第三方库时：

python

undefined

Ignore specific line

忽略特定行

result = third_party_function() # type: ignore[misc]

Ignore entire function

忽略整个函数

def legacy_function(): # type: ignore ...


**Best practice:** Add an issue comment explaining why you're ignoring types.

def legacy_function(): # type: ignore ...


**最佳实践：** 添加注释说明忽略类型检查的原因。

Common Typing Patterns

常见类型注解模式

Optional values:

python

from typing import Optional

def find_workflow(workflow_id: int) -> Optional[Workflow]:
    # Returns Workflow or None if not found
    ...

Union types:

python

from typing import Union

def process_input(data: Union[str, int]) -> str:
    return str(data)

Generic collections:

python

from typing import List, Dict, Set, Tuple

workflows: List[Workflow] = []
metadata: Dict[str, str] = {}
tags: Set[str] = set()
coord: Tuple[int, int] = (10, 20)

Callable types:

python

from typing import Callable

def apply_function(func: Callable[[int], str], value: int) -> str:
    return func(value)

可选值：

python

from typing import Optional

def find_workflow(workflow_id: int) -> Optional[Workflow]:
    # 返回Workflow对象或None（未找到时）
    ...

联合类型：

python

from typing import Union

def process_input(data: Union[str, int]) -> str:
    return str(data)

泛型集合：

python

from typing import List, Dict, Set, Tuple

workflows: List[Workflow] = []
metadata: Dict[str, str] = {}
tags: Set[str] = set()
coord: Tuple[int, int] = (10, 20)

可调用类型：

python

from typing import Callable

def apply_function(func: Callable[[int], str], value: int) -> str:
    return func(value)

Type Stubs

类型存根

Galaxy provides type stubs for untyped dependencies in

lib/galaxy/type_stubs/

Galaxy在

lib/galaxy/type_stubs/

目录下为无类型注解的依赖提供了类型存根文件。

If $ARGUMENTS is "full": Complete Lint Suite

当$ARGUMENTS为"full"时：完整代码检查套件

Run all CI checks locally to ensure your code will pass:

本地运行所有CI检查以确保代码能通过CI验证：

Recommended Order

1. Format check (fast)

1. 格式检查（快速）

tox -e format

If issues found, fix formatting:

若发现问题，修复格式：

make diff-format # or make format

make diff-format # 或使用make format

2. Lint check (fast)

2. 代码规范检查（快速）

tox -e lint

If issues found, fix with:

若发现问题，修复：

ruff check --fix .

3. Type check (medium speed)

3. 类型检查（中等速度）

tox -e mypy

Fix type errors manually (see /galaxy-linting mypy)

手动修复类型错误（参考/galaxy-linting mypy）

4. Docstring check (fast)

4. 文档字符串检查（快速）

tox -e lint_docstring_include_list

5. Client lint (if you changed client code)

5. 客户端代码检查（若修改了客户端代码）

make client-lint make client-format

undefined

make client-lint make client-format

undefined

All-in-One Command

一站式命令

Run all Python checks:

bash

tox -e format && tox -e lint && tox -e mypy && tox -e lint_docstring_include_list

Why this order:

Formatting first - Cheapest to fix, may resolve some lint issues
Linting second - Many auto-fixable issues
Type checking third - Requires manual fixes, benefits from clean lint
Docstring check last - Specific to certain files

运行所有Python检查：

bash

tox -e format && tox -e lint && tox -e mypy && tox -e lint_docstring_include_list

为何按此顺序执行：

先检查格式 - 修复成本最低，可能解决部分代码规范问题
再检查代码规范 - 许多问题可自动修复
然后进行类型检查 - 需手动修复，整洁的代码能降低修复难度
最后检查文档字符串 - 仅针对核心模块

Tox Environment Details

Tox环境详情

tox -e format
:

Runs: black --check, isort --check
Purpose: Verify formatting compliance
Fix with:
```
make format
```
or
```
make diff-format
```

tox -e lint
:

Runs: ruff check, flake8
Purpose: Catch code style violations
Fix with:
```
ruff check --fix .
```
+ manual fixes

tox -e mypy
:

Runs: mypy on selected directories
Purpose: Type checking
Fix with: Add type hints manually

tox -e lint_docstring_include_list
:

Runs: ruff on docstring_include_list modules
Purpose: Enforce docstring standards on core modules
Fix with: Add/improve docstrings

tox -e format
：

执行命令：black --check、isort --check
用途：验证格式合规性
修复方式：
```
make format
```
或
```
make diff-format
```

tox -e lint
：

执行命令：ruff check、flake8
用途：捕获代码风格违规问题
修复方式：
```
ruff check --fix .
```
+ 手动修复

tox -e mypy
：

执行命令：对指定目录运行mypy
用途：类型校验
修复方式：手动添加类型注解

tox -e lint_docstring_include_list
：

执行命令：对docstring_include_list模块运行ruff
用途：对核心模块强制执行文档字符串标准
修复方式：添加/完善文档字符串

CI Workflow File

CI工作流文件

See the full CI setup:

bash

cat .github/workflows/lint.yaml

This shows exactly what CI runs. Match these checks locally to avoid CI failures.

查看完整CI配置：

bash

cat .github/workflows/lint.yaml

该文件展示了CI实际执行的检查内容。本地匹配这些检查可避免CI失败。

Other Lint Targets

其他代码检查目标

Galaxy's Makefile includes additional linting targets for specialized use cases:

Galaxy的Makefile包含针对特殊场景的额外代码检查目标：

API Schema Linting

API Schema检查

Lint OpenAPI schema:

bash

make lint-api-schema

Builds the OpenAPI schema, then lints it with Redocly CLI and checks spelling with codespell. Useful when modifying API endpoints or Pydantic schemas.

检查OpenAPI schema：

bash

make lint-api-schema

生成OpenAPI schema，然后使用Redocly CLI检查，并通过codespell检查拼写。修改API端点或Pydantic schema时推荐使用。

XSD Schema Formatting

XSD Schema格式化

Format Galaxy's tool XSD schema:

bash

make format-xsd

Formats Galaxy's tool XSD schema (

lib/galaxy/tool_util/xsd/galaxy.xsd

) with xmllint. Use when modifying tool schema definitions.

格式化Galaxy工具的XSD schema：

bash

make format-xsd

使用xmllint格式化Galaxy工具的XSD schema（

lib/galaxy/tool_util/xsd/galaxy.xsd

）。修改工具schema定义时使用。

Configuration File Linting

配置文件检查

Lint Galaxy configuration files:

bash

make config-lint              # Lint galaxy.yml
make tool-shed-config-lint    # Lint tool_shed.yml
make reports-config-lint      # Lint reports.yml

Validates YAML configuration files for syntax and structure issues. Run these when modifying Galaxy configuration schemas.

检查Galaxy配置文件：

bash

make config-lint              # 检查galaxy.yml
make tool-shed-config-lint    # 检查tool_shed.yml
make reports-config-lint      # 检查reports.yml

验证YAML配置文件的语法和结构问题。修改Galaxy配置schema时运行这些命令。

File Sources Validation

文件源配置验证

Validate file sources configuration:

bash

make files-sources-lint          # Validate file sources config
make files-sources-lint-verbose  # Verbose output with details

Use when working with file sources plugins or configuration.

验证文件源配置：

bash

make files-sources-lint          # 验证文件源配置
make files-sources-lint-verbose  # 带详细信息的 verbose 输出

处理文件源插件或配置时使用。

Update Lint Requirements

更新代码检查依赖版本

Update pinned lint dependency versions:

bash

make update-lint-requirements

Updates pinned lint dependency versions in

lib/galaxy/dependencies/

. Run this when upgrading linting tools or resolving dependency conflicts.

更新固定的代码检查依赖版本：

bash

make update-lint-requirements

更新

lib/galaxy/dependencies/

目录下的固定代码检查依赖版本。升级代码检查工具或解决依赖冲突时运行。

Troubleshooting

故障排除

"black would reformat" Error

"black would reformat"错误

Symptom: CI fails with "would reformat X files"

Solution:

bash

undefined

症状： CI失败并提示"would reformat X files"

解决方案：

bash

undefined

Run black locally

本地运行black格式化

black .

Or for changed files only

或仅格式化已修改的文件

make diff-format

Commit the formatting changes

提交格式修改

git add -u git commit -m "Apply black formatting"

undefined

git add -u git commit -m "Apply black formatting"

undefined

Ruff Errors Won't Auto-Fix

Ruff错误无法自动修复

Symptom:

ruff check --fix

doesn't fix all issues

Cause: Some ruff rules require manual fixes (e.g., undefined names, logic errors)

Solution:

Run
```
ruff check .
```
to see remaining issues
Read error messages carefully
Fix manually based on error codes
Common manual fixes:
- ```
F821
```
  (undefined name) → Import or define the name
- ```
E501
```
  (line too long) → Break line manually
- ```
B
```
  rules (bugbear) → Logic changes required

症状：

ruff check --fix

无法修复所有问题

原因： 部分ruff规则需手动修复（例如：未定义名称、逻辑错误）

解决方案：

运行
```
ruff check .
```
查看剩余问题
仔细阅读错误信息
根据错误代码手动修复
常见手动修复场景：
- ```
F821
```
  （未定义名称）→ 导入或定义该名称
- ```
E501
```
  （代码行过长）→ 手动拆分代码行
- ```
B
```
  类规则（Bugbear）→ 需要修改逻辑

Flake8 Errors After Passing Ruff

Ruff通过但Flake8失败

Symptom: Ruff passes but flake8 fails in CI

Cause: Flake8 has some rules ruff doesn't cover yet

Solution:

bash

undefined

症状： Ruff检查通过但CI中Flake8失败

原因： Flake8包含一些ruff尚未支持的规则

解决方案：

bash

undefined

Run flake8 locally

本地运行flake8

flake8 .

Fix issues manually

手动修复问题

(Common: line length, docstring issues, specific style rules)

（常见问题：行长度、文档字符串问题、特定风格规则）

undefined

undefined

Tox Environment Creation Fails

Tox环境创建失败

Symptom:

tox -e lint

fails to create environment

Cause: Dependency conflicts or outdated tox cache

Solution:

bash

undefined

症状：

tox -e lint

无法创建环境

原因： 依赖冲突或tox缓存过时

解决方案：

bash

undefined

Recreate tox environment

重新创建tox环境

tox -e lint --recreate

If still failing, clear tox cache

若仍失败，清除tox缓存

rm -rf .tox/ tox -e lint

undefined

rm -rf .tox/ tox -e lint

undefined

Mypy Errors in Unchanged Code

未修改的代码出现Mypy错误

Symptom: Type errors in files you didn't modify

Cause: Your changes altered types used elsewhere

Solution:

Check imports - did you change a function signature?
Run mypy on specific file to see full context:
bash
```
mypy lib/galaxy/managers/your_file.py
```
Fix type annotations to match your changes
Consider if your change needs broader type updates

症状： 未修改的文件中出现类型错误

原因： 您的修改影响了其他文件中使用的类型

解决方案：

检查导入语句 - 是否修改了函数签名？
对特定文件运行mypy以查看完整上下文：
bash
```
mypy lib/galaxy/managers/your_file.py
```
修改类型注解以匹配您的变更
考虑您的变更是否需要更广泛的类型更新

Missing Linting Tools

缺失代码检查工具

Symptom: Command not found (ruff, black, etc.)

Cause: Tools not installed in current environment

Solution:

bash

undefined

症状： 提示命令未找到（ruff、black等）

原因： 当前环境中未安装这些工具

解决方案：

bash

undefined

Install dev dependencies

安装开发依赖

pip install -r lib/galaxy/dependencies/dev-requirements.txt

Or use tox (recommended)

或使用tox（推荐）

tox -e lint # Tox creates isolated environments with correct dependencies

undefined

tox -e lint # Tox会创建包含正确依赖的隔离环境

undefined

Conflicting Formatting Between Tools

工具间格式冲突

Symptom: Black and isort disagree on formatting

Cause: Misconfigured tool settings

Solution:

Galaxy's config already handles this (
```
pyproject.toml
```
sets isort profile to "black")

If you see conflicts, ensure you're using repo's config:

bash

# Check config is being read
black --verbose .
isort --check-only --verbose .

症状： Black与isort在格式上存在分歧

原因： 工具配置错误

解决方案：

Galaxy的配置已处理此问题（
```
pyproject.toml
```
中将isort配置文件设置为"black"）

若仍出现冲突，确保使用仓库的配置：

bash

# 检查是否读取了配置
black --verbose .
isort --check-only --verbose .

Client Lint Failures

客户端代码检查失败

Symptom:

make client-lint

fails with many errors

Solution:

bash

undefined

症状：

make client-lint

失败并出现大量错误

解决方案：

bash

undefined

1. Ensure dependencies installed

1. 确保已安装依赖

make client-node-deps

2. Auto-fix formatting

2. 自动修复格式

make client-format

3. Check remaining issues

3. 检查剩余问题

make client-lint

4. Fix ESLint issues manually

4. 手动修复ESLint问题

(Usually: remove unused vars, add types, fix Vue template issues)

（通常：移除未使用变量、添加类型注解、修复Vue模板问题）

---

---

Additional Resources

额外资源

Configuration files:

```
pyproject.toml
```
- ruff, black, isort, mypy settings
```
.flake8
```
- flake8 configuration
```
tox.ini
```
- tox environment definitions
```
client/.eslintrc.js
```
- ESLint rules
```
client/.prettierrc.yml
```
- Prettier settings

Makefile targets:

bash

undefined

配置文件：

```
pyproject.toml
```
- ruff、black、isort、mypy的设置
```
.flake8
```
- flake8的配置
```
tox.ini
```
- tox环境定义
```
client/.eslintrc.js
```
- ESLint规则
```
client/.prettierrc.yml
```
- Prettier设置

Makefile目标：

bash

undefined

View all linting-related targets

查看所有与代码检查相关的目标

grep -A 2 'format|lint' Makefile


**CI workflow:**
```bash

grep -A 二 'format|lint' Makefile


**CI工作流：**
```bash

See what CI runs

查看CI执行的内容

cat .github/workflows/lint.yaml


**Tool documentation:**
- Ruff: https://docs.astral.sh/ruff/
- Black: https://black.readthedocs.io/
- mypy: https://mypy.readthedocs.io/
- ESLint: https://eslint.org/docs/
- Prettier: https://prettier.io/docs/

**Galaxy-specific patterns:**
- Code style guide: `doc/source/dev/style_guide.md` (if exists)
- Type hints guide: `doc/source/dev/type_hints.md` (if exists)

---

cat .github/workflows/lint.yaml


**工具文档：**
- Ruff: https://docs.astral.sh/ruff/
- Black: https://black.readthedocs.io/
- mypy: https://mypy.readthedocs.io/
- ESLint: https://eslint.org/docs/
- Prettier: https://prettier.io/docs/

**Galaxy特定规范：**
- 代码风格指南：`doc/source/dev/style_guide.md`（若存在）
- 类型注解指南：`doc/source/dev/type_hints.md`（若存在）

---

Quick Command Reference

快速命令参考

Most common workflows:

bash

undefined

最常用工作流：

bash

undefined

Quick check before committing

提交前快速检查

tox -e format && tox -e lint

Fix formatting issues

修复格式问题

make diff-format # Incremental (fast) make format # Full (thorough)

make diff-format # 增量修复（快速） make format # 全量修复（彻底）

Fix auto-fixable lint issues

修复可自动修复的代码规范问题

ruff check --fix .

Modernize Python syntax

升级Python语法至现代风格

make pyupgrade

Full CI simulation

完整模拟CI检查

tox -e format && tox -e lint && tox -e mypy && tox -e lint_docstring_include_list

Client-side

客户端代码检查

make client-lint make client-format

Client-side (granular)

客户端代码检查（细粒度）

make client-eslint # ESLint only make client-format-check # Prettier check only make client-lint-autofix # Auto-fix ESLint

make client-eslint # 仅ESLint检查 make client-format-check # 仅Prettier检查 make client-lint-autofix # 自动修复ESLint问题

Lint API schema (after endpoint changes)

修改端点后检查API schema

make lint-api-schema

Lint config files

检查配置文件

make config-lint make tool-shed-config-lint make reports-config-lint


**Remember:** Run `make diff-format` frequently during development to keep code formatted incrementally!

make config-lint make tool-shed-config-lint make reports-config-lint


**提示：** 开发过程中频繁运行`make diff-format`可保持代码增量格式化！