Goal

For each function <FUNC> in the passed Python file <FILE>, determine if it should be private or public by checking if it's called by Python files or Jupyter notebooks outside <FILE>.

Conventions

• Follow ## Mark Private Functions in .claude/skills/coding.rules.md

Definitions

External Files

• External files = any Python file or Jupyter notebook outside the target file

  • Including:
    • Sibling scripts in the same package (e.g., notes_to_pdf.py calling functions from lib_notes_to_pdf.py)
    • Parent/sibling modules that import from the target
    • CLI entry point scripts
  • Excluding
    • Test files that test the target module, since a function is private even if it's called by a test files

• Note: Functions that form the public API of a library module should be PUBLIC, even if they're not called from a __main__ entry point. If a module exports utility functions for use by other scripts in the package, those are PUBLIC functions

Private Functions

• If the function <FUNC> is not called by any external file, then it should be a private function and should be renamed and prepended with a _

  • E.g., def function -> def _function
  • Include only internal utility functions, helpers, and implementation details

• Modify all the callers of the function <FUNC> to use the new name

• Good (function only called within its own file, so it is renamed private)

  # lib_helper.py
  def public_function():
      _internal_helper()  # Only called within this file, so private.
  
  def _internal_helper():
      pass
  

Public Functions

• If the function <FUNC> is called by external files, then it should be a public function and its name must not start with _

  • This includes functions in shared utility modules called by sibling scripts

• Modify all callers (both external and internal) of the function to use the new name

• Good (function called by an external file, so it stays public)

  # lib_notes_to_pdf.py
  def preprocess_notes(file_name, prefix):  # Called by notes_to_pdf.py, so public.
      _internal_step_1(file_name)  # Private helper.
  
  def _internal_step_1(file_name):  # Only used within lib_notes_to_pdf.py, so private.
      pass
  

Workflow

Find All Functions

• Find all functions in <FILE>

Search for External Calls

• For each function, search the entire codebase for external calls:

  grep -r "<FUNC>" --include="*.py" --include="*.ipynb" --exclude="test_*.py"
  

Classify and Rename

• Classify each function as public or private based on external usage
• Rename functions and update all call sites (both files)
• Verify the changes

Verification

• Grep in the entire codebase to confirm all function calls were renamed correctly bash grep -r "old_name\|new_name" --include="*.py" --include="*.ipynb"
• Run pyright to verify type correctness of modified function invocations
• Run unit tests for the modified files to ensure nothing broke