gpsaggese/helpers / .claude/skills/notebook.refactor_to_utils
notebook.refactor_to_utils
VerifiedMove or add notebook code to a *_utils.py library file
Goal
-
You are an expert Python developer
-
I will pass you a Python file paired with a Jupyter notebook using jupytext in
py:percentformat
Constraints
-
Follow
.claude/skills/coding.rules.mdfor all code -
Important Notes
- Always sync before editing:
uvx jupytext --sync notebook.py - Always sync after editing:
uvx jupytext --sync notebook.py
- Always sync before editing:
Scenarios
- This skill handles two complementary scenarios:
Scenario 1: Moving Existing Functions to Utils
- Extract functions from an existing notebook and move them to utils
Scenario 2: Adding New Code to Utils
- Add new functions or code to the utils file that corresponds to the notebook
Workflow
Identify or Create the Utils File
- Find or create the library file for the notebook, named after it with underscores
- E.g.,
Lesson94-Information_Theory.ipynb->Lesson94_Information_Theory_utils.py - E.g.,
tutorial_advanced.ipynb->tutorial_advanced_utils.py
- E.g.,
Organize Code Structure in Utils File
-
Mirror the notebook's flow, with section separators for each notebook section
- 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(...): ...
- Example:
-
Put each function in the part of the utils file that matches its notebook section
-
Group related functions together
-
Use private functions (prefix
_) for helpers not called from the notebook
Move or Add Functions
For Moving Functions (Scenario 1):
-
Follow these steps:
- Copy all functions from the notebook to the utils file, without changing code
- Remove the functions from the notebook
- Update the notebook cells to call the utils functions
For Adding Functions (Scenario 2):
-
Follow these steps:
- Implement new code directly in the utils file
- Create caller code in the notebook that imports and uses the functions
- Add the code in the matching section of the utils file
Update Notebook to Call Utils
-
Replace function implementations with imports and calls
-
Pattern:
import notebook_name_utils as utils # In code cells: utils.function_name(...) -
Keep each code cell minimal:
# Display results of Cell 2 analysis. utils.cell2_calculate_entropy()
Code Reuse
- Reuse code already in the
*_utils.pyfile and in thehelpersdirectory - Avoid duplication across utils functions. Extract common patterns into helpers
Sync with Jupytext
- After all modifications, sync both files, following
# Code Architecture and Responsibility->## Utilities vs. Notebook Responsibilitiesin.claude/skills/notebook.rules.md:> uvx jupytext --sync <path/to/notebook.py>
Conventions
- Always follow
.claude/skills/notebook.rules.md
Verification
- Confirm no function moved to
*_utils.pychanged behavior - Confirm every notebook cell that held inline code now calls its utils function
- Confirm the
.ipynband paired.pyfile are in sync via Jupytext
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |