Utility functions for interacting with py.js objects

Essentially the py.js version of the Python C API, these functions are used to implement new py.js types or to interact with existing ones.

They are prefixed with PY_.

py.PY_parseArgs(arguments, format)

Arguments parser converting from the user-defined calling conventions to a JS object mapping argument names to values. It serves the same role as PyArg_ParseTupleAndKeywords.

var args = py.PY_parseArgs(
    arguments, ['foo', 'bar', ['baz', 3], ['qux', "foo"]]);

roughly corresponds to the argument spec:

def func(foo, bar, baz=3, qux="foo"):
    pass

Note

a significant difference is that “default values” will be re-evaluated at each call, since they are within the function.

Parameters:
  • arguments – array-like objects holding the args and kwargs passed to the callable, generally the arguments of the caller.
  • format –

    mapping declaration to the actual arguments of the function. A javascript array composed of five possible types of elements:

    • The literal string '*' marks all following parameters as keyword-only, regardless of them having a default value or not [1]. Can only be present once in the parameters list.
    • A string prefixed by *, marks the positional variadic parameter for the function: gathers all provided positional arguments left and makes all following parameters keyword-only [2]. *args is incompatible with *.
    • A string prefixed with **, marks the positional keyword variadic parameter for the function: gathers all provided keyword arguments left and closes the argslist. If present, this must be the last parameter of the format list.
    • A string defines a required parameter, accessible positionally or through keyword
    • A pair of [String, py.object] defines an optional parameter and its default value.

    For simplicity, when not using optional parameters it is possible to use a simple string as the format (using space-separated elements). The string will be split on whitespace and processed as a normal format array.
Returns:

a javascript object mapping argument names to values
Raises:

TypeError if the provided arguments don’t match the format
class py.PY_def(fn)

Type wrapping javascript functions into py.js callables. The wrapped function follows the py.js calling conventions

Parameters:fn (Function) – the javascript function to wrap
Returns:a callable py.js object

Object Protocol

py.PY_hasAttr(o, attr_name)

Returns true if o has the attribute attr_name, otherwise returns false. Equivalent to Python’s hasattr(o, attr_name)

Parameters:
  • o – A py.object
  • attr_name – a javascript String
Return type:

Boolean
py.PY_getAttr(o, attr_name)

Retrieve an attribute attr_name from the object o. Returns the attribute value on success, raises AttributeError on failure. Equivalent to the python expression o.attr_name.

Parameters:
  • o – A py.object
  • attr_name – a javascript String
Returns:

A py.object
Raises:

AttributeError
py.PY_str(o)

Computes a string representation of o, returns the string representation. Equivalent to str(o)

Parameters:o – A py.object
Returns:py.str
py.PY_isInstance(inst, cls)

Returns true if inst is an instance of cls, false otherwise.

py.PY_isSubclass(derived, cls)

Returns true if derived is cls or a subclass thereof.

py.PY_call(callable[, args][, kwargs])

Call an arbitrary python-level callable from javascript.

Parameters:
  • callable – A py.js callable object (broadly speaking, either a class or an object with a __call__ method)
  • args – javascript Array of py.object, used as positional arguments to callable
  • kwargs – javascript Object mapping names to py.object, used as named arguments to callable
Returns:

nothing or py.object
py.PY_isTrue(o)

Returns true if the object is considered truthy, false otherwise. Equivalent to bool(o).

Parameters:o – A py.object
Return type:Boolean
py.PY_not(o)

Inverse of py.PY_isTrue().

py.PY_size(o)

If o is a sequence or mapping, returns its length. Otherwise, raises TypeError.

Parameters:o – A py.object
Returns:Number
Raises:TypeError if the object doesn’t have a length
py.PY_getItem(o, key)

Returns the element of o corresponding to the object key. This is equivalent to o[key].

Parameters:
Returns:

py.object
Raises:

TypeError if o does not support the operation, if key or the return value is not a py.object
py.PY_setItem(o, key, v)

Maps the object key to the value v in o. Equivalent to o[key] = v.

Parameters:
Raises:

TypeError if o does not support the operation, or if key or v are not py.object

Number Protocol

py.PY_add(o1, o2)

Returns the result of adding o1 and o2, equivalent to o1 + o2.

Parameters:
Returns:

py.object
py.PY_subtract(o1, o2)

Returns the result of subtracting o2 from o1, equivalent to o1 - o2.

Parameters:
Returns:

py.object
py.PY_multiply(o1, o2)

Returns the result of multiplying o1 by o2, equivalent to o1 * o2.

Parameters:
Returns:

py.object
py.PY_divide(o1, o2)

Returns the result of dividing o1 by o2, equivalent to o1 / o2.

Parameters:
Returns:

py.object
py.PY_negative(o)

Returns the negation of o, equivalent to -o.

Parameters:o – py.object
Returns:py.object
py.PY_positive(o)

Returns the “positive” of o, equivalent to +o.

Parameters:o – py.object
Returns:py.object
[1]Python 2, which py.js currently implements, does not support Python-level keyword-only parameters (it can be done through the C-API), but it seemed neat and easy enough so there.
[2]due to this and contrary to Python 2, py.js allows arguments other than **kwargs to follow *args.