Merge pull request #181 from rth/api-reference

Add API reference documentation

docs/README.md

@@ -5,6 +5,7 @@
 - [Using Pyodide directly from Javascript](using_pyodide_from_javascript.md)
 - [Using Pyodide from Iodide](using_pyodide_from_iodide.md)
 - [Type conversions](type_conversions.md): describes how data types are shared between Python and Javascript
+- [API Reference](api_reference.md)
 
 ## Developing Pyodide
 

docs/api_reference.md

+# API Reference
+
+*pyodide version 0.1.0*
+
+Backward compatibility of the API is not guaranteed at this point.
+
+
+## Python API
+
+
+### pyodide.open_url(url)
+
+Fetches a given *url* and returns a `io.StringIO` to access its contents.
+
+*Parameters*
+
+| name  | type | description     |
+|-------|------|-----------------|
+| *url* | str  | the URL to open |
+
+
+*Returns*
+
+A `io.StringIO` object with the URL contents./
+
+### pyodide.eval_code(code, ns)
+
+Runs a string of code. The last part of the string may be an expression, in which case, its value is returned.
+
+This function may be overridden to change how `pyodide.runPython` interprets code, for example to perform
+some preprocessing on the Python code first.
+
+*Parameters*
+
+| name   | type  | description           |
+|--------|-------|-----------------------|
+| *code* | str   | the code to evaluate  |
+| *ns*   | dict  | evaluation name space |
+
+
+*Returns*
+
+Either the resulting object or `None`.
+
+
+## Javascript API
+
+### pyodide.loadPackage(names)
+
+Load a package or a list of packages over the network.
+
+This makes the files for the package available in the virtual filesystem.  
+The package needs to be imported from Python before it can be used.
+
+*Parameters*
+
+| name    | type            | description                           |
+|---------|-----------------|---------------------------------------|
+| *names* | {String, Array} | package name, or URL. Can be either a single element, or an array.          |
+
+
+*Returns*
+
+Loading is asynchronous, therefore, this returns a promise.
+
+
+### pyodide.loadedPackage
+
+`Array` with loaded packages.
+
+Use `Object.keys(pyodide.loadedPackage)` to access the names of the
+loaded packages, and `pyodide.loadedPackage[package_name]` to access
+install location for a particular `package_name`.
+
+### pyodide.pyimport(name)
+
+Access a Python object from Javascript.  The object must be in the global Python namespace.
+
+For example, to access the `foo` Python object from Javascript:
+
+   `var foo = pyodide.pyimport('foo')`
+
+*Parameters*
+
+| name    | type   | description          |
+|---------|--------|----------------------|
+| *names* | String | Python variable name |
+
+
+*Returns*
+
+| name      | type    | description                           |
+|-----------|---------|---------------------------------------|
+| *object*  | *any*   | If one of the basic types (string,    |
+|           |         | number, boolean, array, object), the  |
+|           |         | Python object is converted to         |
+|           |         | Javascript and returned.  For other   |
+|           |         | types, a Proxy object to the Python   |
+|           |         | object is returned.                   |
+
+
+### pyodide.repr(obj)
+
+Gets the Python's string representation of an object.
+
+This is equivalent to calling `repr(obj)` in Python.
+
+*Parameters*
+
+| name    | type   | description         |
+|---------|--------|---------------------|
+| *obj*   | *any*  | Input object        |
+
+
+*Returns*
+
+| name       | type    | description                               |
+|------------|---------|-------------------------------------------|
+| *str_repr* | String  | String representation of the input object |
+
+
+### pyodide.runPython(code)
+
+Runs a string of code. The last part of the string may be an expression, in which case, its value is returned.
+
+*Parameters*
+
+| name    | type   | description                    |
+|---------|--------|--------------------------------|
+| *code*  | String | Python code to evaluate        |
+
+
+*Returns*
+
+| name       | type    | description                     |
+|------------|---------|---------------------------------|
+| *jsresult* | *any*   | Result, converted to Javascript |
+
+
+### pyodide.version()
+
+Returns the pyodide version.
+
+It can be either the exact release version (e.g. `0.1.0`), or 
+the latest release version followed by the number of commits since, and
+the git hash of the current commit (e.g. `0.1.0-1-bd84646`).
+
+*Parameters*
+
+None
+
+*Returns*
+
+| name      | type   | description            |
+|-----------|--------|------------------------|
+| *version* | String | Pyodide version string |
+