Skip to content

style(repo): replace yapf with ruff and adopt the Google Python Style Guide's 4-space indent - #302

Merged
aghassemlouei merged 3 commits into
google:mainfrom
digitalresistor:style/ruff-google-style
Oct 20, 2026
Merged

aghassemlouei merged 3 commits into
google:mainfrom
digitalresistor:style/ruff-google-style

Conversation

@digitalresistor

@digitalresistor digitalresistor commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Description

This pull request proposes a repository Python style for discussion. The goal is to match the Google Python Style Guide, which uses 4-space indentation and 80-character lines, and to replace yapf with ruff because of its speed and broad community adoption for Python formatting. Switching back to 2-space indentation later takes a one-line indent-width change in the root ruff.toml file and a rerun of ruff format.

Following the published Google Python Style Guide keeps every Python file in this Google project aligned with Google's corporate coding standards, and gives new projects such as the planned cli/ tool one clear standard from their first commit.

Fixes #304

The branch splits the work into three commits so you can review the tooling apart from the mechanical reformat, and every commit passes the CI checks that apply to it.

  • Commit 1 adds the root ruff.toml file, reformats the 28 tracked Python files that ruff format changes, and fixes every ruff check finding.
  • Commit 1 leaves the 3 empty __init__.py files untouched because they are already formatted.
  • Commit 2 moves the tools/lint.sh script, the tools/requirements.txt file, the CI python-tests job, and the .gemini/styleguide.md Python rules from yapf and pyflakes to ruff.
  • Commit 3 adds a .git-blame-ignore-revs file so git blame and the GitHub blame view skip commit 1.

Configuration

  • The root ruff.toml file sets line-length = 80, indent-width = 4, and target-version = "py311" to match the CI python-version setting.
  • The lint selection covers the E, W, F, and I rule sets.
  • The F rule set carries the pyflakes checks, so the renamed Python Lint and CodeQL py/unused-local-variable Check (ruff) CI step keeps the expectations that the old pyflakes step enforced.
  • The isort settings force one import per line and sort imports within each section, with typing and collections.abc exempt, to follow the Google import style.
  • The exclude list skips .terraform, .venv, venv, node_modules, and Jupyter notebooks, which keeps the vertex-mlops notebook out of this reformat.
  • The tools/requirements.txt file pins ruff==0.17.1 so a new ruff release cannot change formatter output and fail CI without a code change.
  • Ruff also checks Python code blocks inside Markdown files, and every existing Markdown file already passes.
  • Stricter rule sets such as D with the Google docstring convention, N, UP, B, SIM, PL, and RUF stay disabled repository-wide because enabling them requires non-mechanical rewrites of existing code.
  • A new self-contained Python project, such as a future cli/ project, can extend the root ruff.toml file and enable those stricter rule sets.

Lint fixes in commit 1

  • Long string literals use implicit concatenation, and long docstrings and comments wrap at 80 characters.
  • Comparisons against None and False in the gem4gov.py CLI use is and is not.
  • Loop variables named l in the tools/changelog.py, tools/check_links.py, and tools/tfdoc.py scripts and in one test use descriptive names.
  • The analytics app.py SQL queries drop the trailing whitespace after SELECT *.
  • Four assertions in the tests/tools/test_gemini_enterprise_fixes.py test matched single-quoted gem4gov.py source, so they now match the reformatted source.
  • The create_engine signature assertion reads the argument names and the False and None default values from the AST, which keeps it stable across future formatting.
  • The branch adds no noqa comments.

Notes for reviewers

  • Section 1.2 of the code review guide normally rejects cosmetic reformatting, and this pull request exists to decide that formatting baseline in one isolated, behavior-preserving commit.
  • Commit 1 still passes the existing pyflakes CI step, and the ruff CI steps arrive in commit 2 after the code already conforms.
  • Commit 3 records the full SHA of commit 1, so update the .git-blame-ignore-revs file whenever a rebase or squash changes that SHA.
  • A rebase merge keeps the recorded SHA valid, while a squash merge requires a follow-up update with the squashed SHA.
  • Local clones opt in to the ignore list with git config blame.ignoreRevsFile .git-blame-ignore-revs, and GitHub reads the file automatically.
  • Open pull request chore(repo): fix repo-wide lint failures and make tools/lint.sh fail closed #286 also edits the tools/lint.sh script, so whichever lands second needs a small rebase in that file.
  • Open pull request refactor(tests): flatten test suite into tests/ and expand unit coverage #299 moves the tests/scripts/* and tests/tools/* files to a flat tests/ directory, so the reformat of the moved test files produces rename conflicts.
  • Resolving the refactor(tests): flatten test suite into tests/ and expand unit coverage #299 conflicts takes a rerun of ruff format and ruff check --fix after the rebase, followed by a refreshed SHA in the .git-blame-ignore-revs file.

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update

This style and tooling change fits none of the listed types and changes no runtime behavior.

Deployment & Compliance Impact

  • Applicable Regimes:
    • US Region Restricted (e.g., Access Policy constraint)
    • FedRAMP Moderate
    • FedRAMP High
    • DoD IL4
    • DoD IL5
    • General / All
  • NIST 800-53r5 Controls: (If this PR helps satisfy or modifies control implementations, list them here)

This change touches only Python tooling, tests, and CLI source formatting, so it affects no deployment or control implementation.

Checklist

Code Quality & Reusability

  • My code adheres to the Maximize Reusability principle. I have not redefined common elements and have reused existing base configurations and modules where possible.
  • I have checked that no existing module or configuration in modules/ or fast/stages-aw/ can be leveraged for this change.
  • My code follows the established naming conventions outlined in docs/naming-convention.md.

Documentation

  • I have updated the README.md of the modified module or blueprint.
  • I have added/updated documentation for inputs (variables) and outputs.

Security

  • My change adheres to GCP security best practices and the principle of least privilege.
  • I have ensured compliance with the targeted regime (FedRAMP Moderate, FedRAMP High, IL4, IL5, etc.).

Testing

  • I have tested my changes locally.
  • I have included details of my testing in this PR.

The unchecked items do not apply because the change adds no module, Terraform resource, variable, output, or regime-specific configuration.

Testing Performed

The checks below ran locally against Python 3.11 to match CI, using the pinned ruff==0.17.1 from the tools/requirements.txt file.

  • ruff format --check . reports 223 files already formatted, compared with 28 files to reformat on main under the same ruff.toml file.
  • ruff check . passes, compared with 665 findings on main under the same ruff.toml file.
  • pytest passes all 66 tests, the same count as on main.
  • python3 -m pyflakes tools tests blueprints/gemini-enterprise/gem4gov-cli exits cleanly, which shows parity with the F rule set and confirms that commit 1 passes the existing pyflakes CI step.
  • bash -n tools/lint.sh exits cleanly.
  • An AST comparison of every changed Python file against main shows only import order, docstring whitespace, and the lint fixes listed above.
  • The gem4gov.py --help, gem4gov.py license --help, and gem4gov.py license retract --help commands run cleanly and render the same help text, because Click reflows the rewrapped docstrings and help strings.
  • python3 tools/check_boilerplate.py tools tests blueprints reports the same 10 blueprints/gemini-enterprise files on this branch and on main, so that failure predates this change.
  • The full tools/lint.sh run and shellcheck did not run because Terraform and ShellCheck are not installed locally.

@github-actions github-actions Bot added Gemini - Enterprise Gemini Enterprise (GE) related Gemini - Government Gemini for Government (G4G) related Scope - Blueprint Related to solution blueprints in the blueprints directory labels Oct 20, 2026
@digitalresistor
digitalresistor force-pushed the style/ruff-google-style branch from 643ec31 to b8e62a8 Compare October 20, 2026 22:29
@aghassemlouei aghassemlouei added Enhancement New feature or request Project Management Priority - Low Minor polish, typo fixes, or technical debt; nice to have; pick up when time permits Level of Effort - Low Quick, well-defined tasks with no unknowns; takes a few hours up to one day to complete Scope - Fast Related to Fabric FAST deployment stages in the fast directory labels Oct 20, 2026

@aghassemlouei aghassemlouei left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replacing yapf and pyflakes with ruff under a single ruff.toml configuration and enforcing ruff check . plus ruff format --check . in CI is a clean improvement across tools/, tests/, and gem4gov-cli/.

  • Now that #310 is merged into main, .github/workflows/ci.yml on main includes the tflint job, so this branch will need a rebase onto main to resolve the ci.yml conflict.
  • #299 flattens tests/gem4gov_cli/* and tests/tools/* into top-level tests/test_*.py files and expands the unit test suite. Sequencing #299 first (or rebasing #302 after #299 lands and re-running ruff format . and ruff check --fix .) will avoid a multi-file rename and reformat conflict across tests/.

aghassemlouei
aghassemlouei previously approved these changes Oct 20, 2026

@aghassemlouei aghassemlouei left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving the ruff and 4-space Google Python Style Guide adoption. Now that #305 has merged into main (0fb5fcb3), tools/check_boilerplate.py and tools/check_links.py have a small conflict with the .venv ignore additions from #305 (and .git-blame-ignore-revs will need the rebased Commit 1 SHA). Once you rebase this branch onto main, I will re-approve and merge it with rebase so .git-blame-ignore-revs stays valid.

Add a root ruff.toml that follows the Google Python Style Guide with
4-space indentation, an 80-character line limit, a Python 3.11 target,
and the E, W, F, and I rule sets, then run ruff format over every
tracked Python file and let ruff check sort imports one per line.

Fix the remaining ruff check findings by hand. Wrap long string
literals with implicit concatenation, rewrap long docstrings and
comments, compare against None and False with is, rename ambiguous
loop variables named l, and strip trailing whitespace from the
analytics SQL queries.

Update the source-matching assertions in
tests/tools/test_gemini_enterprise_fixes.py to the reformatted
gem4gov.py, and check the create_engine signature and its default
values through the AST.
Run ruff format and ruff check from tools/lint.sh and the CI python
job in place of yapf and pyflakes, and pin ruff in
tools/requirements.txt to the version used for the reformat. Name the
CI lint step after the wider ruff rule selection, and point the Gemini
style guide at ruff format, ruff check, and the root ruff.toml.
Add .git-blame-ignore-revs with the ruff reformat commit so git blame
and the GitHub blame view skip the formatting-only changes.

@aghassemlouei aghassemlouei left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rebased onto main (21f8755b), resolved the .venv ignore conflict in tools/check_boilerplate.py and tools/check_links.py, and updated .git-blame-ignore-revs with the rebased Commit 1 SHA (95907a12).

@aghassemlouei
aghassemlouei merged commit 7595e07 into google:main Oct 20, 2026
7 checks passed
@aghassemlouei aghassemlouei mentioned this pull request Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Enhancement New feature or request Gemini - Enterprise Gemini Enterprise (GE) related Gemini - Government Gemini for Government (G4G) related Level of Effort - Low Quick, well-defined tasks with no unknowns; takes a few hours up to one day to complete Priority - Low Minor polish, typo fixes, or technical debt; nice to have; pick up when time permits Scope - Blueprint Related to solution blueprints in the blueprints directory Scope - Fast Related to Fabric FAST deployment stages in the fast directory

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt the Google Python Style Guide and ruff for Python formatting

2 participants