notebook.refactor_to_utils

Goal

• You are an expert Python developer

• I will pass you a Python file paired with a Jupyter notebook using jupytext in py:percent format

Constraints

• For all the code follow the rules from .claude/skills/coding.rules.md

• Important Notes

  • Always sync before editing: uvx jupytext --sync notebook.py
  • Always sync after editing: uvx jupytext --sync notebook.py

Scenarios

• This skill handles two complementary scenarios:

Scenario 1: Moving Existing Functions to Utils

• When you need to extract functions from an existing notebook and move them to utils

Scenario 2: Adding New Code to Utils

• When you need to add new functions or code to an existing utils file corresponding to the notebook

Workflow

Identify or Create the Utils File

• Find or create the library/utility file that corresponds to the notebook
  • Naming convention: Notebook name with underscores
  • E.g., Lesson94-Information_Theory.ipynb -> Lesson94_Information_Theory_utils.py
  • E.g., tutorial_advanced.ipynb -> tutorial_advanced_utils.py

Organize Code Structure in Utils File

• The utils file should have a structure that mirrors the flow of the notebook

• Use section separators to organize code by notebook sections

  • Example:

    # #############################################################################
    # Cell 1: Visual Bin - Population of Marbles
    # #############################################################################
    
    def cell1_draw_bin_with_marbles_interactive(...):
        ...
    
    def _cell1_helper_function(...):
        ...
    
    # #############################################################################
    # Cell 2: Entropy Calculations
    # #############################################################################
    
    def cell2_calculate_entropy(...):
        ...
    

• Add the functions in the part of the utility file that corresponds to the notebook

• Group related functions together

• Use private functions (prefix with _) for helpers not called from the notebook