From 4fb9a888530fc42a5e4bf70a922a86b608cbc9a7 Mon Sep 17 00:00:00 2001 From: SemTiOne Date: Wed, 17 Jun 2026 13:57:56 +0700 Subject: [PATCH] docs: replace black references with ruff across docs and Makefile Fixes #5248 - Makefile: update comments, help text, FILE_AWARE_LINTERS, .PHONY, lint-quick, lint-fix, pre-commit targets, remove deprecated black-check target - pyproject.toml: update tool configuration comment - AGENTS.md: update coding standards, code quality, and CLI tools sections - llms/*.md: update black references to ruff format Signed-off-by: SemTiOne --- AGENTS.md | 6 +++--- Makefile | 25 +++++++++---------------- llms/mcp-server-python.md | 9 ++------- llms/mcpgateway.md | 2 +- llms/mkdocs.md | 2 +- llms/plugins-llms.md | 2 +- llms/testing.md | 2 +- pyproject.toml | 2 +- 8 files changed, 19 insertions(+), 31 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a88b8c50d8..98ed1da4f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -63,7 +63,7 @@ make serve-ssl # HTTPS on :4444 (creates certs if needed) ### Code Quality ```bash # After writing code -make autoflake isort black pre-commit +make autoflake isort ruff pre-commit # Before committing, use ty, mypy and pyrefly to check just the new files, then run: make ruff bandit interrogate pylint verify @@ -391,7 +391,7 @@ exempt. ## Coding Standards - **Python >= 3.11** with type hints; strict mypy -- **Formatting**: Black (line length 200), isort (profile=black) +- **Formatting**: Ruff format (line length 200), isort (profile=black) - **Linting**: Ruff (`E3`,`E4`,`E7`,`E9`,`F`,`D1`), Pylint per `pyproject.toml` - **Naming**: `snake_case` functions/modules, `PascalCase` classes, `UPPER_CASE` constants - **Imports**: Group per isort sections (stdlib, third-party, first-party `mcpgateway`, local) @@ -456,4 +456,4 @@ When posting PR reviews, issue comments, or any public-facing text on GitHub, us - `make` for build/test automation - `uv` for virtual environment management and for `uv tool run` linter invocations - Dev-group tools installed in the venv: `pytest`, `mypy`, `bandit`, `pre-commit`, `prospector`, etc. (see `pyproject.toml` `[dependency-groups]`) -- Formatters and linters (`black`, `isort`, `ruff`, `pylint`, `vulture`, `interrogate`, `radon`, `yamllint`, `tomlcheck`) are pinned in the `Makefile` and invoked on demand via `uv tool run`; always prefer the Makefile targets (`make black`, `make ruff`, `make pylint`, etc.) over calling the underlying tools directly +- Formatters and linters (`isort`, `ruff`, `pylint`, `vulture`, `interrogate`, `radon`, `yamllint`, `tomlcheck`) are pinned in the `Makefile` and invoked on demand via `uv tool run`; always prefer the Makefile targets (`make ruff`, `make pylint`, etc.) over calling the underlying tools directly diff --git a/Makefile b/Makefile index 6ec746909d..34665f4d91 100644 --- a/Makefile +++ b/Makefile @@ -207,7 +207,7 @@ export UV_BIN # Targets in this Makefile deliberately split how they use `uv`: # # * Execution: invoke tools via `$(VENV_DIR)/bin/` directly (e.g. -# pytest, black, ruff, pylint, python). `uv run` — even with `--active` — +# pytest, ruff, pylint, python). `uv run` — even with `--active` — # has historically resolved against an unexpected environment when the # caller has already `source`d the project venv, producing confusing # "works on my machine" failures. Direct invocation removes the ambiguity: @@ -224,7 +224,7 @@ export UV_BIN # If you add a new target: use `$(VENV_DIR)/bin/` to *run* something and # `uv pip ...` to *install* something. Do not reintroduce `uv run`. # -# Exception — tools invoked via `uvx`: `black`, `isort`, `ruff`, `pylint`, +# Exception — tools invoked via `uvx`: `isort`, `ruff`, `pylint`, # `vulture`, `interrogate`, `radon`, `yamllint`, `tomlcheck`, and # `detect-secrets` are invoked through `uv tool run ` with pinned # versions (see the pins just below). This isolates the tool versions from @@ -236,7 +236,7 @@ export UV_BIN # to PyPI — see DETECT_SECRETS_SPEC below. # # Sub-exception — pylint needs project context: unlike the pure-AST tools -# (ruff, black, isort, vulture, interrogate, radon), pylint does deep type +# (ruff, isort, vulture, interrogate, radon), pylint does deep type # inference via astroid and relies on being able to *import* the project # modules and their runtime dependencies (pydantic, fastapi, …) to avoid # false positives like E1133 (not-an-iterable) and spurious W0246 @@ -3603,11 +3603,10 @@ images: # help: make lint - Run all linters on default targets (mcpgateway) # help: make lint TARGET=myfile.py - Run file-aware linters on specific file # help: make lint myfile.py - Run file-aware linters on a file (shortcut) -# help: make lint-quick myfile.py - Fast linters only (ruff, black, isort) +# help: make lint-quick myfile.py - Fast linters only (ruff, isort) # help: make lint-fix myfile.py - Auto-fix formatting issues # help: make lint-changed - Lint only git-changed files # help: lint - Run the full linting suite (see targets below) -# help: black - Reformat code with black (CHECK=1 for dry-run) # help: autoflake - Remove unused imports / variables with autoflake # help: isort - Organise & sort imports with isort (CHECK=1 for dry-run) # help: pylint - Pylint static analysis @@ -3676,10 +3675,10 @@ LINTERS := isort pylint mypy bandit pydocstyle pycodestyle \ pytype check-manifest markdownlint vulture # Linters that work well with individual files/directories -FILE_AWARE_LINTERS := isort black pylint mypy bandit pydocstyle \ +FILE_AWARE_LINTERS := isort pylint mypy bandit pydocstyle \ pycodestyle ruff pyright vulture markdownlint -.PHONY: lint $(LINTERS) black black-check isort-check ruff-check ruff-fix ruff-format autoflake lint-py lint-yaml lint-json lint-md lint-strict \ +.PHONY: lint $(LINTERS) isort-check ruff-check ruff-fix ruff-format autoflake lint-py lint-yaml lint-json lint-md lint-strict \ lint-count-errors lint-report lint-changed lint-staged lint-commit \ lint-pre-commit lint-pre-push lint-parallel lint-cache-clear lint-stats \ lint-complexity lint-watch lint-watch-quick \ @@ -3744,7 +3743,7 @@ lint-all: ## Convenience targets ## --------------------------------------------------------------------------- ## -# Quick lint - only fast linters (ruff, black, isort) +# Quick lint - only fast linters (ruff, isort) .PHONY: lint-quick lint-quick: @# Handle file arguments @@ -3754,9 +3753,8 @@ lint-quick: else \ actual_target="$(TARGET)"; \ fi; \ - echo "⚡ Quick lint of $$actual_target (ruff + black + isort)..."; \ + echo "⚡ Quick lint of $$actual_target (ruff + isort)..."; \ $(MAKE) --no-print-directory ruff RUFF_MODE=check TARGET="$$actual_target"; \ - $(MAKE) --no-print-directory black CHECK=1 TARGET="$$actual_target"; \ $(MAKE) --no-print-directory isort CHECK=1 TARGET="$$actual_target" # Fix formatting issues @@ -3776,7 +3774,7 @@ lint-fix: fi; \ done; \ echo "🔧 Fixing lint issues in $$actual_target..."; \ - $(MAKE) --no-print-directory black TARGET="$$actual_target"; \ + $(MAKE) --no-print-directory ruff RUFF_MODE=format TARGET="$$actual_target"; \ $(MAKE) --no-print-directory isort TARGET="$$actual_target"; \ $(MAKE) --no-print-directory ruff RUFF_MODE=fix TARGET="$$actual_target" @@ -4084,11 +4082,7 @@ isort: uv ## 🔀 Sort imports (CHECK=1 for dry-run) fi # --- Deprecated aliases (use CHECK=1 instead) --- -# deprecated: black-check - Use "make black CHECK=1" instead (v1.2.0) # deprecated: isort-check - Use "make isort CHECK=1" instead (v1.2.0) -black-check: - $(call deprecated_target,black-check,make black CHECK=1,1.2.0) - @$(MAKE) --no-print-directory black CHECK=1 TARGET="$(TARGET)" isort-check: $(call deprecated_target,isort-check,make isort CHECK=1,1.2.0) @@ -4640,7 +4634,6 @@ lint-parallel: ## 🚀 Run linters in parallel $(UV_BIN) pip install -q pytest-xdist" @# Run fast linters in parallel @$(MAKE) --no-print-directory ruff RUFF_MODE=check TARGET="$(TARGET)" & \ - $(MAKE) --no-print-directory black CHECK=1 TARGET="$(TARGET)" & \ $(MAKE) --no-print-directory isort CHECK=1 TARGET="$(TARGET)" & \ wait @echo "✅ Parallel linting completed!" diff --git a/llms/mcp-server-python.md b/llms/mcp-server-python.md index 590fca72d8..ccfb638346 100644 --- a/llms/mcp-server-python.md +++ b/llms/mcp-server-python.md @@ -111,7 +111,6 @@ dev = [ "pytest>=7.0.0", "pytest-asyncio>=0.21.0", "pytest-cov>=4.0.0", - "black>=23.0.0", "mypy>=1.5.0", "ruff>=0.0.290", ] @@ -126,10 +125,6 @@ packages = ["src/awesome_server"] [project.scripts] awesome-server = "awesome_server.server_fastmcp:main" -[tool.black] -line-length = 100 -target-version = ["py311"] - [tool.mypy] python_version = "3.11" strict = true @@ -178,8 +173,8 @@ install: ## Install in editable mode dev-install: ## Install with dev extras $(PYTHON) -m pip install -e ".[dev]" -format: ## Format (black + ruff --fix) - black . && ruff check --fix . +format: ## Format (ruff format + ruff --fix) + ruff format . && ruff check --fix . lint: ## Lint (ruff, mypy) ruff check . && mypy src/awesome_server diff --git a/llms/mcpgateway.md b/llms/mcpgateway.md index 5ec3c7b1c2..a01a30173a 100644 --- a/llms/mcpgateway.md +++ b/llms/mcpgateway.md @@ -77,7 +77,7 @@ ContextForge: Full Project Overview - HTML coverage only: `make htmlcov` - Selective pytest: `pytest -k "fragment"`, `pytest -m "not slow"` - Lint & static analysis: - - Format & hooks: `make autoflake isort black pre-commit` + - Format & hooks: `make autoflake isort ruff pre-commit` - Static: `make pylint ruff`, full lint: `make lint` - Security/docs QA (as configured): `make bandit interrogate verify check-manifest` - PR readiness (recommended): diff --git a/llms/mkdocs.md b/llms/mkdocs.md index c88348ca74..82ee74ed2c 100644 --- a/llms/mkdocs.md +++ b/llms/mkdocs.md @@ -51,7 +51,7 @@ Notes **Quality & Linting** - Prefer keeping docs consistent with the project's quality workflow: - - `make autoflake isort black pre-commit` (root) to format Python, sort imports, and run hooks. + - `make autoflake isort ruff pre-commit` (root) to format Python, sort imports, and run hooks. - Additional docs authoring guidance: `docs/docs/development/documentation.md`. **Common Tips** diff --git a/llms/plugins-llms.md b/llms/plugins-llms.md index 03e5d69dc3..e0b86d7e2e 100644 --- a/llms/plugins-llms.md +++ b/llms/plugins-llms.md @@ -303,7 +303,7 @@ async function toolPreInvoke({ payload, context }: any) { **Testing Plugins** - Code quality & pre-commit (see AGENTS.md for details): - - `make autoflake isort black pre-commit` formats, orders imports, applies autoflake, and runs pre-commit hooks. + - `make autoflake isort ruff pre-commit` formats, orders imports, applies autoflake, and runs pre-commit hooks. - `make pylint ruff` runs static analysis; fix findings before committing. - `make doctest test` executes doctests then pytest; mirrors CI expectations locally. diff --git a/llms/testing.md b/llms/testing.md index 65f3b190c0..cd195f397f 100644 --- a/llms/testing.md +++ b/llms/testing.md @@ -38,7 +38,7 @@ Testing: Quick Guide for LLMs - HTML report only: `make htmlcov` (auto-runs coverage if `.coverage` missing). **Code Quality & Security** -- Formatting & hooks: `make autoflake isort black pre-commit` +- Formatting & hooks: `make autoflake isort ruff pre-commit` - Static analysis: `make pylint ruff` - Full lint suite (includes web linters after one-time setup): `make lint` and `make lint-web` (install web linters once if needed) - Additional checks (varies by repo config): `make bandit interrogate verify check-manifest` diff --git a/pyproject.toml b/pyproject.toml index 4ebd9f7011..bd0b1ed213 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -367,7 +367,7 @@ mcpgateway = [ ] # -------------------------------------------------------------------- -# 🛠 Tool configurations (black, mypy, etc.) +# 🛠 Tool configurations (ruff, mypy, etc.) # -------------------------------------------------------------------- [tool.pytype] # Directory-specific options: