Rename explain() to friendlyExplain()

Author: grega

README.md

@@ -1,10 +1,8 @@
 # Python Friendly Error Messages
 
 - [ ] Ensure all strings in `src/` are localised
-- [ ] Consider renaming `explain()` to something like `friendlyExplain()`?
 - [ ] Figure out where the built packages should live / be served from
   - [ ] Set up automated testing and publishing through GitHub Actions
-- [ ] Improve (BEM-style) formatting for CSS classes
 - [ ] Open source
 
 A small, runtime-agnostic, library that explains Python error messages in a friendlier way, inspired by [p5.js's Friendly Error System](https://p5js.org/contribute/friendly_error_system/).
@@ -26,7 +24,7 @@ import {
   registerAdapter,
   skulptAdapter,
   pyodideAdapter,
-  explain
+  friendlyExplain
 } from "python-friendly-error-messages";
 
 await loadCopydeckFor(navigator.language); // falls back to "en"
@@ -36,7 +34,7 @@ registerAdapter("skulpt", skulptAdapter);
 registerAdapter("pyodide", pyodideAdapter);
 
 // later, when you have an error string and some code:
-const result = explain({
+const result = friendlyExplain({
   error: rawTracebackString,
   code: editorCode,
   audience: "beginner",

demo/index.html

@@ -18,7 +18,7 @@ <h1>Python Friendly Error Messages - Demo</h1>
   </div>
 
   <script type="module">
-    import { explain, loadCopydeck, registerAdapter, loadCopydeckFor, skulptAdapter, pyodideAdapter } from '../dist/index.browser.js';
+    import { friendlyExplain, loadCopydeck, registerAdapter, loadCopydeckFor, skulptAdapter, pyodideAdapter } from '../dist/index.browser.js';
 
     // example traces with corresponding code
     const examples = [
@@ -121,7 +121,7 @@ <h1>Python Friendly Error Messages - Demo</h1>
 
         for (const example of examples) {
           try {
-            const result = explain({
+            const result = friendlyExplain({
               error: example.trace,
               code: example.code,
               audience: 'beginner',

src/engine.ts

@@ -114,7 +114,7 @@ const pickVariant = (trace: Trace, code: string | undefined, audience: string) =
   return null;
 };
 
-export const explain = (opts: ExplainOptions): ExplainResult => {
+export const friendlyExplain = (opts: ExplainOptions): ExplainResult => {
   if (!S.copy) throw new Error("Copydeck not loaded");
   const audience = opts.audience || "beginner";
   const verbosity = opts.verbosity || "standard";

src/index.browser.ts

@@ -1,5 +1,5 @@
 export type { Trace, ExplainOptions, ExplainResult, CopyDeck, AdapterFn } from "./types.js";
-export { loadCopydeck, registerAdapter, explain } from "./engine.js";
+export { loadCopydeck, registerAdapter, friendlyExplain } from "./engine.js";
 export { skulptAdapter } from "./adapters/skulpt.js";
 export { pyodideAdapter } from "./adapters/pyodide.js";
 export { loadCopydeckFor } from "./loaders.browser.js";

src/index.ts

@@ -1,5 +1,5 @@
 export type { Trace, ExplainOptions, ExplainResult, CopyDeck, AdapterFn } from "./types.js";
-export { loadCopydeck, registerAdapter, explain } from "./engine.js";
+export { loadCopydeck, registerAdapter, friendlyExplain } from "./engine.js";
 export { skulptAdapter } from "./adapters/skulpt.js";
 export { pyodideAdapter } from "./adapters/pyodide.js";
 export { loadCopydeckFor } from "./loaders.js";

tests/engine.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { explain, loadCopydeck, registerAdapter } from "../src/engine";
+import { friendlyExplain, loadCopydeck, registerAdapter } from "../src/engine";
 import { skulptAdapter } from "../src/adapters/skulpt";
 
 const copydeck = {
@@ -70,7 +70,7 @@ describe("engine", () => {
     const raw = `Traceback (most recent call last):
   File "main.py", line 2, in <module>
 NameError: name 'kittens' is not defined`;
-    const res = explain({ error: raw, code, audience: "beginner" });
+    const res = friendlyExplain({ error: raw, code, audience: "beginner" });
     expect(res.trace.type).toBe("NameError");
     expect(res.title).toMatch(/name/i);
     expect(res.summary).toMatch(/kittens/);
@@ -83,7 +83,7 @@ NameError: name 'kittens' is not defined`;
     const raw = `Traceback (most recent call last):
   File "main.py", line 1
 SyntaxError: invalid syntax`;
-    const res = explain({ error: raw, code });
+    const res = friendlyExplain({ error: raw, code });
     expect(res.trace.type).toBe("SyntaxError");
     expect(res.title).toMatch(/colon/i);
     expect(res.patch).toMatch(/:\s*$/);
@@ -94,7 +94,7 @@ SyntaxError: invalid syntax`;
     const raw = `Traceback (most recent call last):
   File "main.py", line 2
 AttributeError: 'list' object has no attribute 'push'`;
-    const res = explain({ error: raw, code });
+    const res = friendlyExplain({ error: raw, code });
     expect(res.trace.type).toBe("AttributeError");
     expect(res.patch).toContain(".append(");
   });

tests/loaders.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { loadCopydeckFor } from "../src/loaders";
-import { explain, loadCopydeck, registerAdapter } from "../src/engine";
+import { friendlyExplain, loadCopydeck, registerAdapter } from "../src/engine";
 import { skulptAdapter } from "../src/adapters/skulpt";
 
 const makeRes = (ok: boolean, data?: any) =>
@@ -25,7 +25,7 @@ describe("loadCopydeckFor", () => {
     await loadCopydeckFor("en-GB");
     registerAdapter("skulpt", skulptAdapter);
 
-    const res = explain({ error: "TypeError: bad", code: "" });
+    const res = friendlyExplain({ error: "TypeError: bad", code: "" });
     expect(res.title).toBe("Python error");
     expect((globalThis.fetch as any).mock.calls[0][0]).toMatch(/copydecks\/en-GB\/copydeck\.json/);
     expect((globalThis.fetch as any).mock.calls[1][0]).toMatch(/copydecks\/en\/copydeck\.json/);
@@ -41,7 +41,7 @@ describe("loadCopydeckFor", () => {
   it("still supports manual loadCopydeck for tests without fetch", () => {
     loadCopydeck(minimalDeck as any);
     registerAdapter("skulpt", skulptAdapter);
-    const res = explain({ error: "NameError: name 'x' is not defined", code: "" });
+    const res = friendlyExplain({ error: "NameError: name 'x' is not defined", code: "" });
     expect(res.title).toBe("Python error");
   });
 });