upgrade-python-3

Upgrade your Python codebase from version 3.x -> 3.11

Example

constants:
  # https://docs.python.org/3/whatsnew/3.11.html#whatsnew311-pep646
  ## Python upgrade prompts
  python_upgrade_prompts:
    - Replace deprecated syntax (e.g., `async` and `await` outside of functions).
    - If debugging errors, utilize fine-grained error locations in tracebacks to provide specific line numbers and code snippets in error messages.
    - If handling multiple exceptions, implement exception groups using the `except*` syntax to manage them in a single block.
    - If there are errors that would benefit from context, enrich exceptions with additional details by using the `.add_note()` method to append notes to exceptions.
    - If there are type annotations already present, apply variadic generics by using `*Ts` for functions and classes that accept multiple types.
    - If there is a `TypedDict` present in the file, mark all types as required or not-required by using `Required[]` and `NotRequired[]` in type definitions.
    - In class methods, implement the `Self` type to provide accurate type hints for methods returning an instance of the class.
    - If parameters should be constrained to string literals, utilize the arbitrary literal string type by using `LiteralString`.
    - If using data classes, adopt data class transforms by using decorators to auto-generate methods like `__init__` and `__repr__`.

steps:
  # Step 1: Update each requirements file
  - name: Update each requirements file
    tools:
      - name: find_files_by_name_with_regex
        arguments:
          find_file_name_pattern: 'requirements*.txt|(^|/)(Pipfile)$|(^|/)(setup.py)$' # Capture requirements.txt variations, Pipfile, and setup.py
        returns: requirements_files
      - name: async_each
        items: '{{ requirements_files }}'
        each_item:
          item_name: requirements_file
          tools:
            - name: edit_file
              arguments:
                path_to_file: '{{ requirements_file }}'
                edit_prompt: |
                  Upgrade all libraries and dependencies to versions that are explicitly compatible with Python 3.11.

                  # Instructions:
                  - **Python Version:** If a Pipfile or setup.py, ensure that the `python_version` entry is set to `>=3.11,<3.12`. Do not include this if this is a requirements.txt file as that is non-standard.
                  - **Dependencies:** Check and update any deprecated libraries that might have replacements in Python 3.11, and add any new libraries leveraging Python 3.11 features.
                  - **Pinned Versions:** If any libraries have versions pinned with `==`, loosen them to `>=` if newer versions are compatible with 3.11.

  # Step 2: Upgrade each .py file
  - name: Upgrade each .py file
    tools:
      - name: find_files_by_name_with_regex
        arguments:
          find_file_name_pattern: '.py$' # Finds all files ending with ".py"
        returns: files
      - name: async_each
        items: '{{ files }}'
        each_item:
          item_name: file
          tools:
            - name: make_variable
              arguments:
                value: |
                  Rewrite this Python code for compatibility with Python 3.11. Be meticulous.
              returns: refactor_prompt
            - name: for_each
              items: '{{ python_upgrade_prompts }}'
              each_item:
                item_name: python_upgrade_prompt
                tools:
                  - name: edit_file
                    arguments:
                      path_to_file: '{{ file }}'
                      edit_prompt: |
                        {{ refactor_prompt }}

                        {{ python_upgrade_prompt }}

  # Step 3: Update README.md
  - name: Update README.md
    tools:
      - name: edit_file
        arguments:
          path_to_file: 'README.md'
          modify_with_diff: true
          edit_prompt: |
            Update the README.md file to reflect that the project now requires Python 3.11.

            - **Mention Python 3.11:** Clearly state that Python 3.11 or later is required.
            - **Installation Instructions:** Update installation steps to ensure they specify installing Python 3.11.
            - **Anything else:** Update any other relevant sections of the README.md file to reflect the changes in Python 3.11.

            IMPORTANT: Do not delete anything unrelated to the changes required for Python 3.11!

  # Theoretically, you could also update other version-specific code like Dockerfiles, virtual environments, etc. but that is out of the scope of this module.