Complement upgrade-pylib Claude Code command#6742

moreal

The command was improved based on the process of updating the json module using the /update-pylib command. Additionally, the script was modified to add import unittest if it is missing.

I worked on #6743 with this pull request's changes.

Summary by CodeRabbit

Documentation
- Added a detailed, step-by-step upgrade workflow for migrating tests, including examples, diff-review guidance, explicit restoration criteria for environment-specific markers, and a new example showing how to restore changes.
New Features
- Enhanced test-upgrade tooling to support single-file and directory upgrades, a verification flow to run and mark tests based on outcomes, and automatic insertion of missing test imports when applying patches.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai

📝 Walkthrough

Walkthrough

Adds a detailed multi-step test-upgrade workflow document and updates scripts/lib_updater.py to detect and insert a missing import unittest into the import block when applying modifications that require it.

Changes

Cohort / File(s)	Summary
Documentation & Workflow `\.claude/commands/upgrade-pylib.md`	Replaced a single-line "Upgrade tests" entry with a comprehensive step-by-step upgrade workflow: quick-upgrade for single files or directories, diff review and restoration criteria for RUSTPYTHON-specific changes, verification/run guidance with marker application, and an example for restoring RUSTPYTHON edits.
Import Detection & Insertion `scripts/lib_updater.py`	Added `has_unittest_import(tree: ast.Module) -> bool` and `find_import_insert_line(tree: ast.Module) -> int`. Modified `apply_patches()` to append `import unittest` into the import block when actual modifications will be applied and the import is missing.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Add tool for easier test updates #6089: Overlaps edits to scripts/lib_updater.py and import/patch behavior.
preparing step to integrate fix_test into lib_updater #6698: Related changes to test-fixing workflow that interact with lib_updater.apply_patches.
Update AI docs #6728: Earlier edits to .claude/commands/upgrade-pylib.md that this change expands.

Suggested reviewers

ShaharNaveh
youknowone
reactive-firewall

Poem

🐰 I hopped through tests, added a line,
An import snug where markers shine,
Docs now guide each careful mend,
Diffs reviewed before I end,
Tiny paws — a tidy vine.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Complement upgrade-pylib Claude Code command' accurately describes the main changes: enhancements to the upgrade-pylib command through improved documentation and updated script functionality.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions

Code has been automatically formatted

The code in this PR has been formatted using:

ruff format
Please pull the latest changes before pushing again:

git pull origin enhance-upgrade-pylib

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@scripts/lib_updater.py`:
- Around line 273-283: has_unittest_import currently treats both "from unittest
import ..." and aliased imports as if the name unittest is available, which is
incorrect for decorators using `@unittest`.*; update has_unittest_import to only
return True when there is an ast.Import whose alias.name equals UT and
alias.asname is None (i.e., a plain "import unittest"), and do not treat
ast.ImportFrom (from unittest import ...) or imports with asname (import
unittest as ut) as satisfying the requirement; reference the has_unittest_import
function and the UT symbol when making this change.
- Around line 286-309: The current logic inserts "import unittest" at line 0
when no imports exist, which can place it before a module docstring or
encoding/shebang; update the insertion logic so it picks a safe line after any
shebang/encoding comments and the module docstring: either enhance
find_import_insert_line to detect and return the end line of the module
docstring (use ast.get_docstring(tree, clean=False) or inspect tree.body[0] if
it's an ast.Expr/ast.Constant string node) and use that end_lineno if > 0, and
also scan the top of the original file lines for a shebang (#!) and PEP-263
encoding comment and advance the insertion line past them; apply this change
where apply_patches calls find_import_insert_line (and keep the check using
modifications, has_unittest_import, and iter_patch_lines intact).

📜 Review details

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 746e71a and 708f227.

📒 Files selected for processing (2)

.claude/commands/upgrade-pylib.md
scripts/lib_updater.py

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.py: Follow PEP 8 style for custom Python code
Use ruff for linting Python code

Files:

scripts/lib_updater.py

🧠 Learnings (12)

📓 Common learnings

Learnt from: ShaharNaveh
Repo: RustPython/RustPython PR: 6089
File: scripts/lib_updater.py:292-297
Timestamp: 2025-08-30T14:40:05.858Z
Learning: In scripts/lib_updater.py, the --inplace flag intentionally writes to orig_file (not remote_file) even though patches are applied to remote_file content. This workflow allows updating the original RustPython test file with patches applied to new upstream CPython content.

Learnt from: CR
Repo: RustPython/RustPython PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-01-14T14:52:10.778Z
Learning: Applies to Lib/test/**/*.py : Use `unittest.skip("TODO: RustPython <reason>")` or `unittest.expectedFailure` with `# TODO: RUSTPYTHON <reason>` comment when marking tests in Lib/ that cannot run

📚 Learning: 2026-01-14T14:52:10.778Z

Learnt from: CR
Repo: RustPython/RustPython PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-01-14T14:52:10.778Z
Learning: Applies to Lib/**/*.py : Minimize modifications to CPython standard library files in the Lib/ directory; these files should be edited very conservatively and modifications should be minimal and only to work around RustPython limitations

Applied to files:

.claude/commands/upgrade-pylib.md

📚 Learning: 2026-01-14T14:52:10.778Z

Learnt from: CR
Repo: RustPython/RustPython PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-01-14T14:52:10.778Z
Learning: Applies to Lib/**/*.py : Add a `# TODO: RUSTPYTHON` comment when modifications are made to Lib/ directory files

Applied to files:

.claude/commands/upgrade-pylib.md

📚 Learning: 2025-08-30T14:40:05.858Z

Learnt from: ShaharNaveh
Repo: RustPython/RustPython PR: 6089
File: scripts/lib_updater.py:292-297
Timestamp: 2025-08-30T14:40:05.858Z
Learning: In scripts/lib_updater.py, the --inplace flag intentionally writes to orig_file (not remote_file) even though patches are applied to remote_file content. This workflow allows updating the original RustPython test file with patches applied to new upstream CPython content.

Applied to files:

.claude/commands/upgrade-pylib.md
scripts/lib_updater.py

📚 Learning: 2026-01-14T14:52:10.778Z

Learnt from: CR
Repo: RustPython/RustPython PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-01-14T14:52:10.778Z
Learning: Applies to Lib/test/**/*.py : Use `unittest.skip("TODO: RustPython <reason>")` or `unittest.expectedFailure` with `# TODO: RUSTPYTHON <reason>` comment when marking tests in Lib/ that cannot run

Applied to files:

.claude/commands/upgrade-pylib.md