pyodide 0.23.4 → 0.24.0

package/pyodide.d.ts

@@ -1,4 +1,4 @@
-// Generated by dts-bundle-generator v6.7.0
+// Generated by dts-bundle-generator v6.13.0
 
 /**
  *
@@ -15,33 +15,6 @@ interface CanvasInterface {
 	setCanvas3D(canvas: HTMLCanvasElement): void;
 	getCanvas3D(): HTMLCanvasElement | undefined;
 }
-declare type PyProxyCache = {
-	cacheId: number;
-	refcnt: number;
-	leaked?: boolean;
-};
-declare type PyProxyProps = {
-	/**
-	 * captureThis tracks whether this should be passed as the first argument to
-	 * the Python function or not. We keep it false by default. To make a PyProxy
-	 * where the ``this`` argument is included, call the :js:meth:`captureThis` method.
-	 */
-	captureThis: boolean;
-	/**
-	 * isBound tracks whether bind has been called
-	 */
-	isBound: boolean;
-	/**
-	 * the ``this`` value that has been bound to the PyProxy
-	 */
-	boundThis?: any;
-	/**
-	 * Any extra arguments passed to bind are used for partial function
-	 * application. These are stored here.
-	 */
-	boundArgs: any[];
-	roundtrip: boolean;
-};
 /** @deprecated Use `import type { PyProxy } from "pyodide/ffi"` instead */
 interface PyProxy {
 	[x: string]: any;
@@ -51,16 +24,9 @@ interface PyProxy {
  * JavaScript. See :ref:`type-translations-pyproxy`.
  */
 declare class PyProxy {
-	/** @private */
-	$$: {
-		ptr: number;
-		cache: PyProxyCache;
-		destroyed_msg?: string;
-	};
-	/** @private */
-	$$props: PyProxyProps;
 	/** @private */
 	$$flags: number;
+	/** @private */
 	static [Symbol.hasInstance](obj: any): obj is PyProxy;
 	/**
 	 * @private
@@ -452,6 +418,272 @@ declare class PyAsyncGeneratorMethods {
 	 */
 	return(v: any): Promise<IteratorResult<any, any>>;
 }
+declare class PySequence extends PyProxy {
+	/** @private */
+	static [Symbol.hasInstance](obj: any): obj is PyProxy;
+}
+/** @deprecated Use `import type { PySequence } from "pyodide/ffi"` instead */
+interface PySequence extends PySequenceMethods {
+}
+declare class PySequenceMethods {
+	get [Symbol.isConcatSpreadable](): boolean;
+	/**
+	 * See :js:meth:`Array.join`. The :js:meth:`Array.join` method creates and
+	 * returns a new string by concatenating all of the elements in the
+	 * :py:class:`~collections.abc.Sequence`.
+	 *
+	 * @param separator A string to separate each pair of adjacent elements of the
+	 * Sequence.
+	 *
+	 * @returns  A string with all Sequence elements joined.
+	 */
+	join(separator?: string): string;
+	/**
+	 * See :js:meth:`Array.slice`. The :js:meth:`Array.slice` method returns a
+	 * shallow copy of a portion of a :py:class:`~collections.abc.Sequence` into a
+	 * new array object selected from ``start`` to ``stop`` (`stop` not included)
+	 * @param start Zero-based index at which to start extraction. Negative index
+	 * counts back from the end of the Sequence.
+	 * @param stop Zero-based index at which to end extraction. Negative index
+	 * counts back from the end of the Sequence.
+	 * @returns A new array containing the extracted elements.
+	 */
+	slice(start?: number, stop?: number): any;
+	/**
+	 * See :js:meth:`Array.lastIndexOf`. Returns the last index at which a given
+	 * element can be found in the Sequence, or -1 if it is not present.
+	 * @param elt Element to locate in the Sequence.
+	 * @param fromIndex Zero-based index at which to start searching backwards,
+	 * converted to an integer. Negative index counts back from the end of the
+	 * Sequence.
+	 * @returns The last index of the element in the Sequence; -1 if not found.
+	 */
+	lastIndexOf(elt: any, fromIndex?: number): number;
+	/**
+	 * See :js:meth:`Array.indexOf`. Returns the first index at which a given
+	 * element can be found in the Sequence, or -1 if it is not present.
+	 * @param elt Element to locate in the Sequence.
+	 * @param fromIndex Zero-based index at which to start searching, converted to
+	 * an integer. Negative index counts back from the end of the Sequence.
+	 * @returns The first index of the element in the Sequence; -1 if not found.
+	 */
+	indexOf(elt: any, fromIndex?: number): number;
+	/**
+	 * See :js:meth:`Array.forEach`. Executes a provided function once for each
+	 * ``Sequence`` element.
+	 * @param callbackfn A function to execute for each element in the ``Sequence``. Its
+	 * return value is discarded.
+	 * @param thisArg A value to use as ``this`` when executing ``callbackFn``.
+	 */
+	forEach(callbackfn: (elt: any) => void, thisArg?: any): void;
+	/**
+	 * See :js:meth:`Array.map`. Creates a new array populated with the results of
+	 * calling a provided function on every element in the calling ``Sequence``.
+	 * @param callbackfn A function to execute for each element in the ``Sequence``. Its
+	 * return value is added as a single element in the new array.
+	 * @param thisArg A value to use as ``this`` when executing ``callbackFn``.
+	 */
+	map(callbackfn: (elt: any, index: number, array: any) => void, thisArg?: any): unknown[];
+	/**
+	 * See :js:meth:`Array.filter`. Creates a shallow copy of a portion of a given
+	 * ``Sequence``, filtered down to just the elements from the given array that pass
+	 * the test implemented by the provided function.
+	 * @param callbackfn A function to execute for each element in the array. It
+	 * should return a truthy value to keep the element in the resulting array,
+	 * and a falsy value otherwise.
+	 * @param thisArg A value to use as ``this`` when executing ``predicate``.
+	 */
+	filter(predicate: (elt: any, index: number, array: any) => boolean, thisArg?: any): any[];
+	/**
+	 * See :js:meth:`Array.some`. Tests whether at least one element in the
+	 * ``Sequence`` passes the test implemented by the provided function.
+	 * @param callbackfn A function to execute for each element in the
+	 * ``Sequence``. It should return a truthy value to indicate the element
+	 * passes the test, and a falsy value otherwise.
+	 * @param thisArg A value to use as ``this`` when executing ``predicate``.
+	 */
+	some(predicate: (value: any, index: number, array: any[]) => unknown, thisArg?: any): boolean;
+	/**
+	 * See :js:meth:`Array.every`. Tests whether every element in the ``Sequence``
+	 * passes the test implemented by the provided function.
+	 * @param callbackfn A function to execute for each element in the
+	 * ``Sequence``. It should return a truthy value to indicate the element
+	 * passes the test, and a falsy value otherwise.
+	 * @param thisArg A value to use as ``this`` when executing ``predicate``.
+	 */
+	every(predicate: (value: any, index: number, array: any[]) => unknown, thisArg?: any): boolean;
+	/**
+	 * See :js:meth:`Array.reduce`. Executes a user-supplied "reducer" callback
+	 * function on each element of the Sequence, in order, passing in the return
+	 * value from the calculation on the preceding element. The final result of
+	 * running the reducer across all elements of the Sequence is a single value.
+	 * @param callbackfn A function to execute for each element in the ``Sequence``. Its
+	 * return value is discarded.
+	 * @param thisArg A value to use as ``this`` when executing ``callbackfn``.
+	 */
+	reduce(callbackfn: (previousValue: any, currentValue: any, currentIndex: number, array: any) => any, initialValue?: any): any;
+	/**
+	 * See :js:meth:`Array.reduceRight`. Applies a function against an accumulator
+	 * and each value of the Sequence (from right to left) to reduce it to a
+	 * single value.
+	 * @param callbackfn A function to execute for each element in the Sequence.
+	 * Its return value is discarded.
+	 * @param thisArg A value to use as ``this`` when executing ``callbackFn``.
+	 */
+	reduceRight(callbackfn: (previousValue: any, currentValue: any, currentIndex: number, array: any) => any, initialValue: any): any;
+	/**
+	 * See :js:meth:`Array.at`. Takes an integer value and returns the item at
+	 * that index.
+	 * @param index Zero-based index of the Sequence element to be returned,
+	 * converted to an integer. Negative index counts back from the end of the
+	 * Sequence.
+	 * @returns The element in the Sequence matching the given index.
+	 */
+	at(index: number): any;
+	/**
+	 * The :js:meth:`Array.concat` method is used to merge two or more arrays.
+	 * This method does not change the existing arrays, but instead returns a new
+	 * array.
+	 * @param rest Arrays and/or values to concatenate into a new array.
+	 * @returns A new Array instance.
+	 */
+	concat(...rest: ConcatArray<any>[]): any[];
+	/**
+	 * The  :js:meth:`Array.includes` method determines whether a Sequence
+	 * includes a certain value among its entries, returning true or false as
+	 * appropriate.
+	 * @param elt
+	 * @returns
+	 */
+	includes(elt: any): any;
+	/**
+	 * The :js:meth:`Array.entries` method returns a new iterator object that
+	 * contains the key/value pairs for each index in the ``Sequence``.
+	 * @returns A new iterator object.
+	 */
+	entries(): IterableIterator<[
+		number,
+		any
+	]>;
+	/**
+	 * The :js:meth:`Array.keys` method returns a new iterator object that
+	 * contains the keys for each index in the ``Sequence``.
+	 * @returns A new iterator object.
+	 */
+	keys(): IterableIterator<number>;
+	/**
+	 * The :js:meth:`Array.values` method returns a new iterator object that
+	 * contains the values for each index in the ``Sequence``.
+	 * @returns A new iterator object.
+	 */
+	values(): IterableIterator<any>;
+	/**
+	 * The :js:meth:`Array.find` method returns the first element in the provided
+	 * array that satisfies the provided testing function.
+	 * @param predicate A function to execute for each element in the
+	 * ``Sequence``. It should return a truthy value to indicate a matching
+	 * element has been found, and a falsy value otherwise.
+	 * @param thisArg A value to use as ``this`` when executing ``predicate``.
+	 * @returns The first element in the ``Sequence`` that satisfies the provided
+	 * testing function.
+	 */
+	find(predicate: (value: any, index: number, obj: any[]) => any, thisArg?: any): any;
+	/**
+	 * The :js:meth:`Array.findIndex` method returns the index of the first
+	 * element in the provided array that satisfies the provided testing function.
+	 * @param predicate A function to execute for each element in the
+	 * ``Sequence``. It should return a truthy value to indicate a matching
+	 * element has been found, and a falsy value otherwise.
+	 * @param thisArg A value to use as ``this`` when executing ``predicate``.
+	 * @returns The index of the first element in the ``Sequence`` that satisfies
+	 * the provided testing function.
+	 */
+	findIndex(predicate: (value: any, index: number, obj: any[]) => any, thisArg?: any): number;
+}
+declare class PyMutableSequence extends PyProxy {
+	/** @private */
+	static [Symbol.hasInstance](obj: any): obj is PyProxy;
+}
+/** @deprecated Use `import type { PyMutableSequence } from "pyodide/ffi"` instead */
+interface PyMutableSequence extends PyMutableSequenceMethods {
+}
+declare class PyMutableSequenceMethods {
+	/**
+	 * The :js:meth:`Array.reverse` method reverses a ``MutableSequence`` in
+	 * place.
+	 * @returns A reference to the same ``MutableSequence``
+	 */
+	reverse(): this;
+	/**
+	 * The :js:meth:`Array.sort` method sorts the elements of a
+	 * ``MutableSequence`` in place.
+	 * @param compareFn A function that defines the sort order.
+	 * @returns A reference to the same ``MutableSequence``
+	 */
+	sort(compareFn?: (a: any, b: any) => number): this;
+	/**
+	 * The :js:meth:`Array.splice` method changes the contents of a
+	 * ``MutableSequence`` by removing or replacing existing elements and/or
+	 * adding new elements in place.
+	 * @param start Zero-based index at which to start changing the
+	 * ``MutableSequence``.
+	 * @param deleteCount An integer indicating the number of elements in the
+	 * ``MutableSequence`` to remove from ``start``.
+	 * @param items The elements to add to the ``MutableSequence``, beginning from
+	 * ``start``.
+	 * @returns An array containing the deleted elements.
+	 */
+	splice(start: number, deleteCount?: number, ...items: any[]): void;
+	/**
+	 * The :js:meth:`Array.push` method adds the specified elements to the end of
+	 * a ``MutableSequence``.
+	 * @param elts The element(s) to add to the end of the ``MutableSequence``.
+	 * @returns The new length property of the object upon which the method was
+	 * called.
+	 */
+	push(...elts: any[]): any;
+	/**
+	 * The :js:meth:`Array.pop` method removes the last element from a
+	 * ``MutableSequence``.
+	 * @returns The removed element from the ``MutableSequence``; undefined if the
+	 * ``MutableSequence`` is empty.
+	 */
+	pop(): void;
+	/**
+	 * The :js:meth:`Array.shift` method removes the first element from a
+	 * ``MutableSequence``.
+	 * @returns The removed element from the ``MutableSequence``; undefined if the
+	 * ``MutableSequence`` is empty.
+	 */
+	shift(): void;
+	/**
+	 * The :js:meth:`Array.unshift` method adds the specified elements to the
+	 * beginning of a ``MutableSequence``.
+	 * @param elts The elements to add to the front of the ``MutableSequence``.
+	 * @returns The new length of the ``MutableSequence``.
+	 */
+	unshift(...elts: any[]): any;
+	/**
+	 * The :js:meth:`Array.copyWithin` method shallow copies part of a
+	 * ``MutableSequence`` to another location in the same ``MutableSequence``
+	 * without modifying its length.
+	 * @param target Zero-based index at which to copy the sequence to.
+	 * @param start Zero-based index at which to start copying elements from.
+	 * @param end Zero-based index at which to end copying elements from.
+	 * @returns The modified ``MutableSequence``.
+	 */
+	copyWithin(target: number, start?: number, end?: number): any;
+	/**
+	 * The :js:meth:`Array.fill` method changes all elements in an array to a
+	 * static value, from a start index to an end index.
+	 * @param value Value to fill the array with.
+	 * @param start Zero-based index at which to start filling. Default 0.
+	 * @param end Zero-based index at which to end filling. Default
+	 * ``list.length``.
+	 * @returns
+	 */
+	fill(value: any, start?: number, end?: number): any;
+}
 declare class PyAwaitable extends PyProxy {
 	/** @private */
 	static [Symbol.hasInstance](obj: any): obj is PyProxy;
@@ -693,7 +925,7 @@ declare function loadPackage(names: string | PyProxy | Array<string>, options?:
 	messageCallback?: (message: string) => void;
 	errorCallback?: (message: string) => void;
 	checkIntegrity?: boolean;
-}, errorCallbackDeprecated?: (message: string) => void): Promise<void>;
+}): Promise<void>;
 declare class PythonError extends Error {
 	/**
 	 * The address of the error we are wrapping. We may later compare this
@@ -713,18 +945,21 @@ declare class PythonError extends Error {
 declare type InFuncType = () => null | undefined | string | ArrayBuffer | Uint8Array | number;
 declare function setStdin(options?: {
 	stdin?: InFuncType;
+	read?: (buffer: Uint8Array) => number;
 	error?: boolean;
 	isatty?: boolean;
 	autoEOF?: boolean;
 }): void;
 declare function setStdout(options?: {
-	batched?: (a: string) => void;
-	raw?: (a: number) => void;
+	batched?: (output: string) => void;
+	raw?: (charCode: number) => void;
+	write?: (buffer: Uint8Array) => number;
 	isatty?: boolean;
 }): void;
 declare function setStderr(options?: {
-	batched?: (a: string) => void;
-	raw?: (a: number) => void;
+	batched?: (output: string) => void;
+	raw?: (charCode: number) => void;
+	write?: (buffer: Uint8Array) => number;
 	isatty?: boolean;
 }): void;
 declare type NativeFS = {
@@ -758,6 +993,8 @@ declare class PyodideAPI {
 		PyBuffer: typeof PyBuffer;
 		PyBufferView: typeof PyBufferView;
 		PythonError: typeof PythonError;
+		PySequence: typeof PySequence;
+		PyMutableSequence: typeof PyMutableSequence;
 	};
 	/** @hidden */
 	static setStdin: typeof setStdin;
@@ -840,14 +1077,13 @@ declare class PyodideAPI {
 	 *    (optional)
 	 * @param options.checkIntegrity If true, check the integrity of the downloaded
 	 *    packages (default: true)
-	 * @param errorCallbackDeprecated @ignore
 	 * @async
 	 */
 	static loadPackagesFromImports(code: string, options?: {
 		messageCallback?: (message: string) => void;
 		errorCallback?: (message: string) => void;
 		checkIntegrity?: boolean;
-	}, errorCallbackDeprecated?: (message: string) => void): Promise<void>;
+	}): Promise<void>;
 	/**
 	 * Runs a string of Python code from JavaScript, using :py:func:`~pyodide.code.eval_code`
 	 * to evaluate the code. If the last statement in the Python code is an
@@ -860,12 +1096,32 @@ declare class PyodideAPI {
 	 *        Defaults to :js:attr:`pyodide.globals`.
 	 * @param options.locals An optional Python dictionary to use as the locals.
 	 *        Defaults to the same as ``globals``.
+	 * @param options.filename An optional string to use as the filename. Defaults
+	 *        to "<exec>". If the filename does not start with "<" and end with ">",
+	 *        the source code will be added to the Python linecache and tracebacks
+	 *        will show source lines.
 	 * @returns The result of the Python code translated to JavaScript. See the
 	 *          documentation for :py:func:`~pyodide.code.eval_code` for more info.
+	 * @example
+	 * async function main(){
+	 *   const pyodide = await loadPyodide();
+	 *   console.log(pyodide.runPython("1 + 2"));
+	 *   // 3
+	 *
+	 *   const globals = pyodide.toPy({ x: 3 });
+	 *   console.log(pyodide.runPython("x + 1", { globals }));
+	 *   // 4
+	 *
+	 *   const locals = pyodide.toPy({ arr: [1, 2, 3] });
+	 *   console.log(pyodide.runPython("sum(arr)", { locals }));
+	 *   // 6
+	 * }
+	 * main();
 	 */
 	static runPython(code: string, options?: {
 		globals?: PyProxy;
 		locals?: PyProxy;
+		filename?: string;
 	}): any;
 	/**
 	 * Run a Python code string with top level await using
@@ -880,7 +1136,7 @@ declare class PyodideAPI {
 	 *
 	 *    let result = await pyodide.runPythonAsync(`
 	 *        from js import fetch
-	 *        response = await fetch("./repodata.json")
+	 *        response = await fetch("./pyodide-lock.json")
 	 *        packages = await response.json()
 	 *        # If final statement is an expression, its value is returned to JavaScript
 	 *        len(packages.packages.object_keys())
@@ -900,12 +1156,17 @@ declare class PyodideAPI {
 	 * Defaults to :js:attr:`pyodide.globals`.
 	 * @param options.locals An optional Python dictionary to use as the locals.
 	 *        Defaults to the same as ``globals``.
+	 * @param options.filename An optional string to use as the filename. Defaults
+	 *        to "<exec>". If the filename does not start with "<" and end with ">",
+	 *        the source code will be added to the Python linecache and tracebacks
+	 *        will show source lines.
 	 * @returns The result of the Python code translated to JavaScript.
 	 * @async
 	 */
 	static runPythonAsync(code: string, options?: {
 		globals?: PyProxy;
 		locals?: PyProxy;
+		filename?: string;
 	}): Promise<any>;
 	/**
 	 * Registers the JavaScript object ``module`` as a JavaScript module named
@@ -1079,10 +1340,16 @@ declare class PyodideAPI {
 	 * @deprecated
 	 */
 	static get PythonError(): typeof PythonError;
+	/**
+	 * Turn on or off debug mode. In debug mode, some error messages are improved
+	 * at a performance cost.
+	 * @param debug If true, turn debug mode on. If false, turn debug mode off.
+	 * @returns The old value of the debug flag.
+	 */
+	static setDebug(debug: boolean): boolean;
 }
 /** @hidetype */
 export declare type PyodideInterface = typeof PyodideAPI;
-export declare type Py2JsResult = any;
 /**
  * See documentation for loadPyodide.
  * @private
@@ -1100,6 +1367,10 @@ export declare type ConfigType = {
 	jsglobals?: object;
 	args: string[];
 	_node_mounts: string[];
+	env: {
+		[key: string]: string;
+	};
+	packages: string[];
 };
 /**
  * Load the main Pyodide wasm module and initialize it.
@@ -1107,6 +1378,16 @@ export declare type ConfigType = {
  * @returns The :ref:`js-api-pyodide` module.
  * @memberof globalThis
  * @async
+ * @example
+ * async function main() {
+ *   const pyodide = await loadPyodide({
+ *     fullStdLib: true,
+ *     homedir: "/pyodide",
+ *     stdout: (msg) => console.log(`Pyodide: ${msg}`),
+ *   });
+ *   console.log("Loaded Pyodide");
+ * }
+ * main();
  */
 export declare function loadPyodide(options?: {
 	/**
@@ -1119,13 +1400,23 @@ export declare function loadPyodide(options?: {
 	 */
 	indexURL?: string;
 	/**
+	 * The file path where packages will be cached in node. If a package
+	 * exists in ``packageCacheDir`` it is loaded from there, otherwise it is
+	 * downloaded from the JsDelivr CDN and then cached into ``packageCacheDir``.
+	 * Only applies when running in node; ignored in browsers.
+	 *
+	 * Default: same as indexURL
+	 */
+	packageCacheDir?: string;
+	/**
+	 * The URL from which Pyodide will load the Pyodide ``pyodide-lock.json`` lock
 	 * file. You can produce custom lock files with :py:func:`micropip.freeze`.
-	 * Default: ```${indexURL}/repodata.json```
+	 * Default: ```${indexURL}/pyodide-lock.json```
 	 */
 	lockFileURL?: string;
 	/**
 	 * The home directory which Pyodide will use inside virtual file system.
-	 * Default: ``"/home/pyodide"``
+	 * This is deprecated, use ``{env: {HOME : some_dir}}`` instead.
 	 */
 	homedir?: string;
 	/**
@@ -1136,23 +1427,32 @@ export declare function loadPyodide(options?: {
 	fullStdLib?: boolean;
 	/**
 	 * The URL from which to load the standard library ``python_stdlib.zip``
-	 * file. This URL includes the most of the Python stadard library. Some
+	 * file. This URL includes the most of the Python standard library. Some
 	 * stdlib modules were unvendored, and can be loaded separately
-	 * with ``fullStdLib=true`` option or by their package name.
+	 * with ``fullStdLib: true`` option or by their package name.
 	 * Default: ```${indexURL}/python_stdlib.zip```
 	 */
 	stdLibURL?: string;
 	/**
 	 * Override the standard input callback. Should ask the user for one line of
-	 * input.
+	 * input. The :js:func:`pyodide.setStdin` function is more flexible and
+	 * should be preferred.
 	 */
 	stdin?: () => string;
 	/**
-	 * Override the standard output callback.
+	 * Override the standard output callback. The :js:func:`pyodide.setStdout`
+	 * function is more flexible and should be preferred in most cases, but
+	 * depending on the ``args`` passed to ``loadPyodide``, Pyodide may write to
+	 * stdout on startup, which can only be controlled by passing a custom
+	 * ``stdout`` function.
 	 */
 	stdout?: (msg: string) => void;
 	/**
-	 * Override the standard error output callback.
+	 * Override the standard error output callback. The
+	 * :js:func:`pyodide.setStderr` function is more flexible and should be
+	 * preferred in most cases, but depending on the ``args`` passed to
+	 * ``loadPyodide``, Pyodide may write to stdout on startup, which can only
+	 * be controlled by passing a custom ``stdout`` function.
 	 */
 	stderr?: (msg: string) => void;
 	/**
@@ -1167,6 +1467,27 @@ export declare function loadPyodide(options?: {
 	 * more details. Default: ``[]``
 	 */
 	args?: string[];
+	/**
+	 * Environment variables to pass to Python. This can be accessed inside of
+	 * Python at runtime via :py:data:`os.environ`. Certain environment variables change
+	 * the way that Python loads:
+	 * https://docs.python.org/3.10/using/cmdline.html#environment-variables
+	 * Default: ``{}``.
+	 * If ``env.HOME`` is undefined, it will be set to a default value of
+	 * ``"/home/pyodide"``
+	 */
+	env?: {
+		[key: string]: string;
+	};
+	/**
+	 * A list of packages to load as Pyodide is initializing.
+	 *
+	 * This is the same as loading the packages with
+	 * :js:func:`pyodide.loadPackage` after Pyodide is loaded except using the
+	 * ``packages`` option is more efficient because the packages are downloaded
+	 * while Pyodide bootstraps itself.
+	 */
+	packages?: string[];
 	/**
 	 * @ignore
 	 */