Merge pull request #85 from Distributive-Network/Xmader/feat/atob-btoa

Implement `atob`/`btoa` APIs

Author: Xmader

python/pythonmonkey/__init__.py

@@ -6,5 +6,6 @@
 import importlib.metadata
 __version__= importlib.metadata.version(__name__)
 
-# Load the module by default to make `console` globally available
+# Load the module by default to make `console`/`atob`/`btoa` globally available
 require("console")
+require("base64")

python/pythonmonkey/builtin_modules/base64.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file    base64.d.ts
+ * @brief   TypeScript type declarations for base64.py
+ * @author  Tom Tang <[email protected]>
+ * @date    July 2023
+ */
+
+/**
+ * Decode base64 string
+ * @param b64 A string containing base64-encoded data.
+ * @see https://html.spec.whatwg.org/multipage/webappapis.html#dom-atob-dev
+ */
+export declare function atob(b64: string): string;
+
+/**
+ * Create a base64-encoded ASCII string from a binary string
+ * @param data The binary string to encode.
+ * @see https://html.spec.whatwg.org/multipage/webappapis.html#dom-btoa-dev
+ */
+export declare function btoa(data: string): string;

python/pythonmonkey/builtin_modules/base64.py

@@ -0,0 +1,23 @@
+# @file     base64.py
+# @author   Tom Tang <[email protected]>, Hamada Gasmallah <[email protected]>
+# @date     July 2023
+
+import base64
+
+atob = lambda b64: str(base64.standard_b64decode(b64), 'latin1')
+btoa = lambda data: str(base64.standard_b64encode(bytes(data, 'latin1')), 'latin1')
+
+# Make `atob`/`btoa` globally available
+import pythonmonkey as pm
+pm.eval(r"""(atob, btoa) => {
+  if (!globalThis.atob) {
+    globalThis.atob = atob;
+  }
+  if (!globalThis.btoa) {
+    globalThis.btoa = btoa;
+  }
+}""")(atob, btoa)
+
+# Module exports
+exports['atob'] = atob # type: ignore
+exports['btoa'] = btoa # type: ignore

python/pythonmonkey/builtin_modules/console.js

@@ -6,6 +6,7 @@
 const { customInspectSymbol, format } = require("util");
 
 /** @typedef {(str: string) => void} WriteFn */
+/** @typedef {{ write: WriteFn }} IOWriter */
 
 /**
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Console_API
@@ -21,14 +22,20 @@ class Console {
 
   /**
    * Console constructor, form 1
-   * @param {object} stdout - object with write method
-   * @param {object} stderr - object with write method
-   * @param {boolean} ignoreErrors - currently unused in PythonMonkey
+   * @overload
+   * @param {IOWriter} stdout - object with write method
+   * @param {IOWriter} stderr - object with write method
+   * @param {boolean=} ignoreErrors - currently unused in PythonMonkey
    * @see https://nodejs.org/api/console.html#new-consolestdout-stderr-ignoreerrors
    */
   /**
    * Console constructor, form 2
-   * @param {object} options - options object
+   * @overload
+   * @param {ConsoleConstructorOptions} options - options object
+   * @typedef {object} ConsoleConstructorOptions
+   * @property {IOWriter} stdout - object with write method
+   * @property {IOWriter} stderr - object with write method
+   * @property {boolean=} ignoreErrors - currently unused in PythonMonkey
    */
   constructor(stdout, stderr, ignoreErrors)
   {

python/pythonmonkey/global.d.ts

@@ -11,12 +11,28 @@ declare const python: {
   };
   /** Python `print` */
   print(...values: any): void;
-  /** Python `sys.stdout.write`. Write the given string to stdout. */
-  stdout_write(s: string): void;
-  /** Python `sys.stderr.write`. Write the given string to stderr. */
-  stderr_write(s: string): void;
+  /** Python `eval` */
+  eval(code: string, globals?: Record<string, any>, locals?: Record<string, any>): any;
+  /** Python `exec` */
+  exec(code: string, globals?: Record<string, any>, locals?: Record<string, any>): void;
+  /** Python `sys.stdout`. */
+  stdout: {
+    /** Write the given string to stdout. */
+    write(s: string): number;
+    read(n: number): string;
+  };
+  /** Python `sys.stderr`. */
+  stderr: {
+    /** Write the given string to stderr. */
+    write(s: string): number;
+    read(n: number): string;
+  };
   /** Python `os.getenv`. Get an environment variable, return undefined if it doesn't exist. */
   getenv(key: string): string | undefined;
+  /** Python `exit`. Exit the program. */
+  exit(exitCode: number): never;
+  /** Loads a python module using importlib, prefills it with an exports object and returns the module. */
+  load(filename: string): object;
   /** Python `sys.path` */
   paths: string[];
 };
@@ -25,7 +41,12 @@ declare const python: {
 declare function pmEval(code: string): any;
 
 // Expose our own `console` as a property of the global object
-declare const console: import("console").Console;
+// XXX: ↓↓↓ we must use "var" here
+declare var console: import("console").Console;
+
+// Expose `atob`/`btoa` as properties of the global object
+declare var atob: typeof import("base64").atob;
+declare var btoa: typeof import("base64").btoa;
 
 // Keep this in sync with both https://hg.mozilla.org/releases/mozilla-esr102/file/a03fde6/js/public/Promise.h#l331
 //                        and  https://github.com/nodejs/node/blob/v20.2.0/deps/v8/include/v8-promise.h#L30

tests/js/test-atob-btoa.simple

@@ -0,0 +1,58 @@
+/**
+ * @file        test-atob-btoa.simple
+ *              Simple test which ensures atob/btoa works
+ * @author      Tom Tang <[email protected]>
+ * @date        July 2023
+ */
+
+function expect(a) {
+  return {
+    toBe(b) {
+      if (a !== b) throw new Error(`'${a}' does not equal to '${b}'`);
+    }
+  }
+}
+
+/*!
+ * Modified from https://github.com/oven-sh/bun/blob/bun-v0.6.12/test/js/web/util/atob.test.js
+ * Bun
+ * MIT License
+ */
+
+// 
+// atob
+// 
+expect(atob("YQ==")).toBe("a");
+expect(atob("YWI=")).toBe("ab");
+expect(atob("YWJj")).toBe("abc");
+expect(atob("YWJjZA==")).toBe("abcd");
+expect(atob("YWJjZGU=")).toBe("abcde");
+expect(atob("YWJjZGVm")).toBe("abcdef");
+expect(atob("zzzz")).toBe("Ï<ó");
+expect(atob("")).toBe("");
+expect(atob("null")).toBe("žée");
+expect(atob("6ek=")).toBe("éé");
+// expect(atob("6ek")).toBe("éé"); // FIXME (Tom Tang): binascii.Error: Incorrect padding
+expect(atob("gIE=")).toBe("€");
+// expect(atob("zz")).toBe("Ï"); // FIXME (Tom Tang): same here
+// expect(atob("zzz")).toBe("Ï<");
+expect(atob("zzz=")).toBe("Ï<");
+expect(atob(" YQ==")).toBe("a");
+expect(atob("YQ==\u000a")).toBe("a");
+
+// 
+// btoa
+// 
+expect(btoa("a")).toBe("YQ==");
+expect(btoa("ab")).toBe("YWI=");
+expect(btoa("abc")).toBe("YWJj");
+expect(btoa("abcd")).toBe("YWJjZA==");
+expect(btoa("abcde")).toBe("YWJjZGU=");
+expect(btoa("abcdef")).toBe("YWJjZGVm");
+expect(typeof btoa).toBe("function");
+expect(btoa("")).toBe("");
+expect(btoa("null")).toBe("bnVsbA==");
+expect(btoa("undefined")).toBe("dW5kZWZpbmVk");
+expect(btoa("[object Window]")).toBe("W29iamVjdCBXaW5kb3dd");
+expect(btoa("éé")).toBe("6ek=");
+expect(btoa("\u0080\u0081")).toBe("gIE=");