From galaxy-dev
Galaxy code linting, formatting, and type checking. Run checks, auto-fix formatting, Python lint, client lint, mypy type checks. Use for: ruff, flake8, black, isort, darker, autoflake, pyupgrade, eslint, prettier, mypy, tox, make format, make diff-format, code style, lint failures, CI lint checks, formatting errors, type errors, codespell, redocly, api schema, xsd, config lint.
How this skill is triggered — by the user, by Claude, or both
Slash command
/galaxy-dev:galaxy-lintingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Persona: You are a senior Galaxy developer specializing in code quality, style enforcement, and CI compliance.
Persona: You are a senior Galaxy developer specializing in code quality, style enforcement, and CI compliance.
Arguments:
Parse $ARGUMENTS to determine which guidance to provide.
Galaxy uses multiple linting tools enforced through CI:
tox -e lint, tox -e format, tox -e mypy, tox -e lint_docstring_include_list| 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 |
Run the fastest feedback loop to catch most issues:
# 1. Check formatting (fast - shows what would change)
tox -e format
# 2. Check linting (catches style violations)
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.
Galaxy provides multiple ways to auto-fix formatting issues.
Fix only changed lines using darker (via Makefile):
# Fix formatting for uncommitted changes only
make diff-format
What it does:
origin/dev branchFormat entire codebase:
# Format all Python files
make format
What it does:
Fix ruff auto-fixable issues:
ruff check --fix .
Remove unused imports:
make remove-unused-imports
Modernize Python syntax (pyupgrade):
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:
make client-format
# During development (fast):
make diff-format
# Before committing (thorough):
make format
tox -e lint # Verify no remaining issues
Galaxy's Python linting stack consists of multiple tools, each with a specific purpose.
Fast, modern Python linter that replaces many tools.
Check for issues:
ruff check .
Auto-fix issues:
ruff check --fix .
Configuration: pyproject.toml under [tool.ruff] and [tool.ruff.lint]
Key rule categories:
list[int] instead of List[int])Common errors and fixes:
F401 - Unused import → Remove import or use # noqa: F401F841 - Unused variable → Remove or rename to _E501 - Line too long (>120 chars) → Break into multiple linesUP - Use modern syntax → Let ruff auto-fix with --fixOpinionated code formatter - ensures consistent style.
Check what would change:
black --check .
Format files:
black .
Configuration: pyproject.toml under [tool.black]
Common scenarios:
black . locallySorts and organizes imports into groups.
Check import order:
isort --check .
Fix import order:
isort .
Configuration: pyproject.toml under [tool.isort]
Import groups (in order):
Example:
# 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
Traditional Python linter - still used alongside ruff.
Run flake8:
flake8 .
Configuration: .flake8 file in repository root
Note: Ruff covers most flake8 checks. Galaxy maintains flake8 for specific rules not yet in ruff.
Applies black/isort only to changed lines.
Format changed code:
make diff-format
How it works:
origin/devUse when:
GitHub Actions runs these checks:
.github/workflows/lint.yaml defines CI linting pipelineformat, lint, mypy, lint_docstring_include_listTo match CI locally:
tox -e format # Check formatting
tox -e lint # Check linting
Python linting configuration:
pyproject.toml - ruff, black, isort, mypy config.flake8 - flake8 rules and exclusionstox.ini - tox environment definitionsRead these files to understand specific rules:
# View ruff config
grep -A 20 '\[tool.ruff\]' pyproject.toml
# View black config
grep -A 10 '\[tool.black\]' pyproject.toml
# View flake8 config
cat .flake8
Galaxy's client-side code (Vue.js, TypeScript) uses ESLint and Prettier.
Ensure Node.js dependencies are installed:
make client-node-deps
This installs ESLint, Prettier, and related packages in client/node_modules/.
Check for linting issues:
make client-lint
Configuration: client/.eslintrc.js
Rules enforced:
Common issues:
_Format client code:
make client-format
Configuration: client/.prettierrc.yml
Formats:
Integration with ESLint:
prettier plugin to avoid conflictsGalaxy's Makefile provides fine-grained control over client linting:
Run only ESLint (no Prettier check):
make client-eslint
Run only Prettier check (no ESLint):
make client-format-check
Auto-fix ESLint errors with --fix (no Prettier):
make client-lint-autofix
Pre-commit hook linting (for specific file paths):
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)Run ESLint directly:
cd client
npm run eslint
Run Prettier directly:
cd client
npm run prettier:check # Check
npm run prettier:write # Fix
# 1. Install dependencies (if needed)
make client-node-deps
# 2. Check for issues
make client-lint
# 3. Auto-fix formatting
make client-format
# 4. Manually fix remaining ESLint issues
# (Edit files based on lint output)
# 5. Verify fixed
make client-lint
Galaxy uses mypy for static type checking with strict mode enabled.
Check types across codebase:
tox -e mypy
Check specific file or directory:
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 hintsdisallow_any_generics - Must specify generic types (e.g., List[str] not List)warn_return_any - Warn on returning Anywarn_unused_ignores - Warn on unnecessary # type: ignore commentsError: "Function is missing a type annotation"
# Bad
def process_workflow(workflow_id):
...
# Good
def process_workflow(workflow_id: int) -> dict:
...
Error: "Need type annotation for variable"
# Bad
workflows = []
# Good
workflows: List[Workflow] = []
Error: "Incompatible return value type"
# Bad
def get_workflow() -> Workflow:
return None # Error: None is not Workflow
# Good
from typing import Optional
def get_workflow() -> Optional[Workflow]:
return None # OK: Optional[Workflow] allows None
Error: "Incompatible types in assignment"
# Bad
workflow_id: int = "123" # Error: str is not int
# Good
workflow_id: int = 123
Error: "Cannot determine type of variable"
# Bad (mypy can't infer type)
result = get_complex_data()
# Good (explicit annotation)
result: Dict[str, Any] = get_complex_data()
When mypy is wrong or you're working with untyped libraries:
# 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.
Optional values:
from typing import Optional
def find_workflow(workflow_id: int) -> Optional[Workflow]:
# Returns Workflow or None if not found
...
Union types:
from typing import Union
def process_input(data: Union[str, int]) -> str:
return str(data)
Generic collections:
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:
from typing import Callable
def apply_function(func: Callable[[int], str], value: int) -> str:
return func(value)
Galaxy provides type stubs for untyped dependencies in lib/galaxy/type_stubs/.
Run all CI checks locally to ensure your code will pass:
# 1. Format check (fast)
tox -e format
# If issues found, fix formatting:
make diff-format # or make format
# 2. Lint check (fast)
tox -e lint
# If issues found, fix with:
ruff check --fix .
# 3. Type check (medium speed)
tox -e mypy
# Fix type errors manually (see /galaxy-linting mypy)
# 4. Docstring check (fast)
tox -e lint_docstring_include_list
# 5. Client lint (if you changed client code)
make client-lint
make client-format
Run all Python checks:
tox -e format && tox -e lint && tox -e mypy && tox -e lint_docstring_include_list
Why this order:
tox -e format:
make format or make diff-formattox -e lint:
ruff check --fix . + manual fixestox -e mypy:
tox -e lint_docstring_include_list:
See the full CI setup:
cat .github/workflows/lint.yaml
This shows exactly what CI runs. Match these checks locally to avoid CI failures.
Galaxy's Makefile includes additional linting targets for specialized use cases:
Lint OpenAPI schema:
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.
Format Galaxy's tool XSD schema:
make format-xsd
Formats Galaxy's tool XSD schema (lib/galaxy/tool_util/xsd/galaxy.xsd) with xmllint. Use when modifying tool schema definitions.
Lint Galaxy configuration files:
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.
Validate file sources configuration:
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.
Update pinned lint dependency versions:
make update-lint-requirements
Updates pinned lint dependency versions in lib/galaxy/dependencies/. Run this when upgrading linting tools or resolving dependency conflicts.
Symptom: CI fails with "would reformat X files"
Solution:
# Run black locally
black .
# Or for changed files only
make diff-format
# Commit the formatting changes
git add -u
git commit -m "Apply black formatting"
Symptom: ruff check --fix doesn't fix all issues
Cause: Some ruff rules require manual fixes (e.g., undefined names, logic errors)
Solution:
ruff check . to see remaining issuesF821 (undefined name) → Import or define the nameE501 (line too long) → Break line manuallyB rules (bugbear) → Logic changes requiredSymptom: Ruff passes but flake8 fails in CI
Cause: Flake8 has some rules ruff doesn't cover yet
Solution:
# Run flake8 locally
flake8 .
# Fix issues manually
# (Common: line length, docstring issues, specific style rules)
Symptom: tox -e lint fails to create environment
Cause: Dependency conflicts or outdated tox cache
Solution:
# Recreate tox environment
tox -e lint --recreate
# If still failing, clear tox cache
rm -rf .tox/
tox -e lint
Symptom: Type errors in files you didn't modify
Cause: Your changes altered types used elsewhere
Solution:
mypy lib/galaxy/managers/your_file.py
Symptom: Command not found (ruff, black, etc.)
Cause: Tools not installed in current environment
Solution:
# Install dev dependencies
pip install -r lib/galaxy/dependencies/dev-requirements.txt
# Or use tox (recommended)
tox -e lint # Tox creates isolated environments with correct dependencies
Symptom: Black and isort disagree on formatting
Cause: Misconfigured tool settings
Solution:
pyproject.toml sets isort profile to "black")# Check config is being read
black --verbose .
isort --check-only --verbose .
Symptom: make client-lint fails with many errors
Solution:
# 1. Ensure dependencies installed
make client-node-deps
# 2. Auto-fix formatting
make client-format
# 3. Check remaining issues
make client-lint
# 4. Fix ESLint issues manually
# (Usually: remove unused vars, add types, fix Vue template issues)
Configuration files:
pyproject.toml - ruff, black, isort, mypy settings.flake8 - flake8 configurationtox.ini - tox environment definitionsclient/.eslintrc.js - ESLint rulesclient/.prettierrc.yml - Prettier settingsMakefile targets:
# View all linting-related targets
grep -A 2 'format\|lint' Makefile
CI workflow:
# See what CI runs
cat .github/workflows/lint.yaml
Tool documentation:
Galaxy-specific patterns:
doc/source/dev/style_guide.md (if exists)doc/source/dev/type_hints.md (if exists)Most common workflows:
# Quick check before committing
tox -e format && tox -e lint
# Fix formatting issues
make diff-format # Incremental (fast)
make format # Full (thorough)
# Fix auto-fixable lint issues
ruff check --fix .
# Modernize Python syntax
make pyupgrade
# Full CI simulation
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
# Lint API schema (after endpoint changes)
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!
npx claudepluginhub arash77/galaxy-claude-marketplace --plugin galaxy-devAutomates format-lint-resolve pipelines for code editing tasks. Discovers linters from pyproject.toml/.pre-commit-config.yaml/package.json, fixes ruff/mypy/bandit issues, ensures quality before completion.
Sets up Python code quality toolchain with ruff linting/formatting, mypy type checking, complexity gating, dead code detection, pre-commit hooks, pyproject.toml config, and Makefile targets.
Runs deterministic Python quality checks: linting/formatting (ruff), type checking (ty), tests (pytest), policy validation, and pre-commit workflows. Reports grouped results by category.