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

Move or Add Functions

For Moving Functions (Scenario 1):

• Follow these steps:

  1. Copy all functions from the notebook to the utils file (without changing code)
  2. Remove the functions from the notebook
  3. Update notebook cells to call the utils functions

For Adding Functions (Scenario 2):

• Follow these steps:

  1. Implement new code directly in the utils file
  2. Create caller code in the notebook that imports and uses the functions
  3. Add the code in the appropriate section following the utils file structure

Update Notebook to Call Utils

• Replace function implementations with imports and function calls

• Pattern:

  import notebook_name_utils as utils
  
  # In code cells:
  utils.function_name(...)
  

• Each code cell should be minimal:

  # Display results of Cell 2 analysis.
  utils.cell2_calculate_entropy()
  

Code Reuse

• Reuse code already existing in the *_utils.py file
• Reuse code already existing in the helpers directory
• Avoid duplication across utils functions
• Extract common patterns into helper functions

Sync with Jupytext

• After all modifications are complete, sync to update both files following the conventions in # Code Architecture and Responsibility -> ## Utilities vs. Notebook Responsibilities in .claude/skills/notebook.rules.md:

  > uvx jupytext --sync <path/to/notebook.py>
  

Conventions

• Always follow the conventions and guidelines in .claude/skills/notebook.rules.md

Verification

• Confirm no function moved to *_utils.py changed behavior
• Confirm every notebook cell that used to hold inline code now calls the corresponding utils function
• Confirm the .ipynb and paired .py file are in sync via Jupytext