feat(protocol-designer): utility functions for Python generation (#17419)

# Overview

These are utility functions for rendering basic objects into Python, to
be used for Python code generation from Protocol Designer. AUTH-1385

## Test Plan and Hands on Testing

Added unit tests for all the JavaScript -> Python types we support.

I'm also using this code in my private branch.

## Review requests

Is this the right directory for a utils file? I noticed that there's
both:
- `step-generation/src/utils`
- `step-generation/lib/utils`

What's the difference?

I'm planning to use these functions from both `protocol-designer` and
`step-generation`.

## Risk assessment

Low: nothing calls this code right now.

---------

Co-authored-by: Jethary Alcid <[email protected]>

Author: ddcc4

step-generation/src/__tests__/pythonFormat.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+import { formatPyStr, formatPyValue } from '../utils/pythonFormat'
+
+describe('pythonFormat utils', () => {
+  it('format string', () => {
+    expect(
+      formatPyStr(`Funky quotes " '\nNewline\tUnicode µ, Backslash\\`)
+    ).toEqual(`"Funky quotes \\" '\\nNewline\\tUnicode µ, Backslash\\\\"`)
+  })
+
+  it('format number', () => {
+    expect(formatPyValue(3.14)).toBe('3.14')
+    expect(formatPyValue(-1e-10)).toBe('-1e-10')
+    // this is the valid way to write these values in Python:
+    expect(formatPyValue(-1 / 0)).toBe('float("-Infinity")')
+    expect(formatPyValue(0 / 0)).toBe('float("NaN")')
+  })
+
+  it('format boolean', () => {
+    expect(formatPyValue(true)).toBe('True')
+    expect(formatPyValue(false)).toBe('False')
+  })
+
+  it('format list', () => {
+    expect(
+      formatPyValue(['hello', 'world', 2.71828, true, false, undefined])
+    ).toBe('["hello", "world", 2.71828, True, False, None]')
+  })
+
+  it('format dict', () => {
+    // null:
+    expect(formatPyValue(null)).toBe('None')
+    // zero entries:
+    expect(formatPyValue({})).toBe('{}')
+    // one entry:
+    expect(formatPyValue({ one: 'two' })).toBe('{"one": "two"}')
+    expect(formatPyValue({ 3: 4 })).toBe('{"3": 4}')
+    // multiple entries:
+    expect(formatPyValue({ yes: true, no: false })).toBe(
+      '{\n    "yes": True,\n    "no": False,\n}'
+    )
+    // nested entries:
+    expect(
+      formatPyValue({ hello: 'world', nested: { inner: 5, extra: 6 } })
+    ).toBe(
+      '{\n    "hello": "world",\n    "nested": {\n        "inner": 5,\n        "extra": 6,\n    },\n}'
+    )
+  })
+})

step-generation/src/utils/index.ts

@@ -27,4 +27,5 @@ export * from './safePipetteMovements'
 export * from './wasteChuteCommandsUtil'
 export * from './createTimelineFromRunCommands'
 export * from './constructInvariantContextFromRunCommands'
+export * from './pythonFormat'
 export const uuid: () => string = uuidv4

step-generation/src/utils/pythonFormat.ts

@@ -0,0 +1,65 @@
+/** Utility functions for Python code generation. */
+
+const INDENT = '    '
+
+/** Indent each of the lines in `text`. */
+export function indentPyLines(text: string): string {
+  return text
+    .split('\n')
+    .map(line => (line ? INDENT + line : line))
+    .join('\n')
+}
+
+/** Render an arbitrary JavaScript value to Python. */
+export function formatPyValue(value: any): string {
+  switch (typeof value) {
+    case 'undefined':
+      return 'None'
+    case 'boolean':
+      return value ? 'True' : 'False'
+    case 'number':
+      // `float("Infinity")` and `float("NaN")` is how you write those values in Python
+      return Number.isFinite(value) ? `${value}` : `float("${value}")`
+    case 'string':
+      return formatPyStr(value)
+    case 'object':
+      if (value === null) {
+        return 'None'
+      } else if (Array.isArray(value)) {
+        return formatPyList(value)
+      } else {
+        return formatPyDict(value as Record<string, any>)
+      }
+    default:
+      throw Error('Cannot render value as Python', { cause: value })
+  }
+}
+
+/** Render the string value to Python. */
+export function formatPyStr(str: string): string {
+  // Later, we can do something more elegant like outputting 'single-quoted' if str contains
+  // double-quotes, but for now stringify() produces a valid and properly escaped Python string.
+  return JSON.stringify(str)
+}
+
+/** Render an array value as a Python list. */
+export function formatPyList(list: any[]): string {
+  return `[${list.map(value => formatPyValue(value)).join(', ')}]`
+}
+
+/** Render an object as a Python dict. */
+export function formatPyDict(dict: Record<string, any>): string {
+  const dictEntries = Object.entries(dict)
+  // Render dict on single line if it has 1 entry, else render 1 entry per line.
+  if (dictEntries.length <= 1) {
+    return `{${dictEntries
+      .map(([key, value]) => `${formatPyStr(key)}: ${formatPyValue(value)}`)
+      .join(', ')}}`
+  } else {
+    return `{\n${indentPyLines(
+      dictEntries
+        .map(([key, value]) => `${formatPyStr(key)}: ${formatPyValue(value)}`)
+        .join(',\n')
+    )},\n}`
+  }
+}