OpenParable
Skip to content
← Back to skills

Upgrade Pylib

Development
upgrade-pylib

Upgrade Pylib is an Agent Skill for development published in the RustPython/RustPython repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Upgrade a Python standard library module from CPython into RustPython using scripts/update_lib and then triage and mark remaining failures.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/RustPython/RustPython/blob/HEAD/.agents/skills/upgrade-pylib/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/upgrade-pylib, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Upgrade Python Library from CPython

Upgrade a Python standard library module from CPython to RustPython.

Arguments

  • Library name or path (examples: inspect, asyncio, json, cpython/Lib/inspect.py, cpython/Lib/json/)

Important: Report Tool Issues First

If scripts/update_lib shows a bug, missing automation, or unexpected behavior, stop the upgrade and report the tooling issue first, including:

  1. What you were trying to do:
  • Library name.
  • Full command used.
  1. What went wrong or what is missing.
  2. Expected vs actual behavior.

Workflow

  1. Run quick upgrade with update_lib:
  • python3 scripts/update_lib quick <module>
  • or python3 scripts/update_lib quick cpython/Lib/<module>.py
  • or python3 scripts/update_lib quick cpython/Lib/<module>/

This step copies library files, patches tests while preserving markers where possible, runs tests, auto-marks new failures, removes stale @unittest.expectedFailure, and creates a commit.

If warnings like WARNING: TestCFoo does not exist in remote file appear, class structure changed and some markers must be restored manually.

  1. Review diff and restore RustPython-specific changes:
  • Run git diff Lib/test/test_<module>.
  • Restore only changes with explicit RUSTPYTHON comments.
  • Do not restore unrelated upstream CPython changes.
  1. Investigate failing dependent tests:
  • Get dependencies:

    cargo run --release -- scripts/update_lib deps <module>
    
  • Find direct dependent test modules from the - [ ] <module>: line.

  • Run dependent tests and collect failures:

    cargo run --release -- -m test <test_modules...> 2>&1 | grep -E "^(FAIL|ERROR):"
    
  • For each failing test identifier, investigate with the investigate-test-failure workflow.

  1. Mark remaining failures with auto-mark:
  • python3 scripts/update_lib auto-mark Lib/test/test_<module>.py --mark-failure
  • or python3 scripts/update_lib auto-mark Lib/test/test_<module>/ --mark-failure

Note: --mark-failure marks all current failures including regressions; review carefully.

  1. Handle panics manually:
  • For tests that panic/crash/hang, use @unittest.skip("TODO: RUSTPYTHON; ...") rather than expectedFailure.
  1. Handle class-specific failures:
  • If only one subclass fails (for example TestCFoo but not TestPyFoo), move marker to the failing subclass override.
  1. Commit test-fix markers as a separate commit:
git add -u && git commit -m "Mark failing tests"

Example usage

upgrade-pylib inspect
upgrade-pylib json
upgrade-pylib asyncio
upgrade-pylib cpython/Lib/inspect.py
upgrade-pylib cpython/Lib/json/

Notes

  • The cpython/ directory should contain the CPython source used for sync.
  • scripts/update_lib modes:
    • quick: patch + auto-mark
    • migrate: patch only
    • auto-mark: mark failures only
    • copy-lib: copy library files only
  • Patching transfers @unittest.expectedFailure and @unittest.skip with TODO: RUSTPYTHON markers where possible.
  • The tool does not preserve every RustPython-specific change; always review and restore explicit RUSTPYTHON-marked logic.