1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
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_``.
.. function:: py.PY_parseArgs(arguments, format)
Arguments parser converting from the :ref:`user-defined calling
conventions <types-methods-python-call>` 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:
.. code-block:: python
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.
:param arguments: array-like objects holding the args and kwargs
passed to the callable, generally the
``arguments`` of the caller.
:param 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 [#kwonly]_. 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
[#star-args]_. ``*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 :ref:`the py.js calling conventions
<types-methods-python-call>`
:param Function fn: the javascript function to wrap
:returns: a callable py.js object
Object Protocol
---------------
.. function:: 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)``
:param o: A :class:`py.object`
:param attr_name: a javascript ``String``
:rtype: ``Boolean``
.. function:: 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``.
:param o: A :class:`py.object`
:param attr_name: a javascript ``String``
:returns: A :class:`py.object`
:raises: ``AttributeError``
.. function:: py.PY_str(o)
Computes a string representation of ``o``, returns the string
representation. Equivalent to ``str(o)``
:param o: A :class:`py.object`
:returns: :class:`py.str`
.. function:: py.PY_isInstance(inst, cls)
Returns ``true`` if ``inst`` is an instance of ``cls``, ``false``
otherwise.
.. function:: py.PY_isSubclass(derived, cls)
Returns ``true`` if ``derived`` is ``cls`` or a subclass thereof.
.. function:: py.PY_call(callable[, args][, kwargs])
Call an arbitrary python-level callable from javascript.
:param callable: A ``py.js`` callable object (broadly speaking,
either a class or an object with a ``__call__``
method)
:param args: javascript Array of :class:`py.object`, used as
positional arguments to ``callable``
:param kwargs: javascript Object mapping names to
:class:`py.object`, used as named arguments to
``callable``
:returns: nothing or :class:`py.object`
.. function:: py.PY_isTrue(o)
Returns ``true`` if the object is considered truthy, ``false``
otherwise. Equivalent to ``bool(o)``.
:param o: A :class:`py.object`
:rtype: Boolean
.. function:: py.PY_not(o)
Inverse of :func:`py.PY_isTrue`.
.. function:: py.PY_size(o)
If ``o`` is a sequence or mapping, returns its length. Otherwise,
raises ``TypeError``.
:param o: A :class:`py.object`
:returns: ``Number``
:raises: ``TypeError`` if the object doesn't have a length
.. function:: py.PY_getItem(o, key)
Returns the element of ``o`` corresponding to the object
``key``. This is equivalent to ``o[key]``.
:param o: :class:`py.object`
:param key: :class:`py.object`
:returns: :class:`py.object`
:raises: ``TypeError`` if ``o`` does not support the operation, if
``key`` or the return value is not a :class:`py.object`
.. function:: py.PY_setItem(o, key, v)
Maps the object ``key`` to the value ``v`` in ``o``. Equivalent to
``o[key] = v``.
:param o: :class:`py.object`
:param key: :class:`py.object`
:param v: :class:`py.object`
:raises: ``TypeError`` if ``o`` does not support the operation, or
if ``key`` or ``v`` are not :class:`py.object`
Number Protocol
---------------
.. function:: py.PY_add(o1, o2)
Returns the result of adding ``o1`` and ``o2``, equivalent to
``o1 + o2``.
:param o1: :class:`py.object`
:param o2: :class:`py.object`
:returns: :class:`py.object`
.. function:: py.PY_subtract(o1, o2)
Returns the result of subtracting ``o2`` from ``o1``, equivalent
to ``o1 - o2``.
:param o1: :class:`py.object`
:param o2: :class:`py.object`
:returns: :class:`py.object`
.. function:: py.PY_multiply(o1, o2)
Returns the result of multiplying ``o1`` by ``o2``, equivalent to
``o1 * o2``.
:param o1: :class:`py.object`
:param o2: :class:`py.object`
:returns: :class:`py.object`
.. function:: py.PY_divide(o1, o2)
Returns the result of dividing ``o1`` by ``o2``, equivalent to
``o1 / o2``.
:param o1: :class:`py.object`
:param o2: :class:`py.object`
:returns: :class:`py.object`
.. function:: py.PY_negative(o)
Returns the negation of ``o``, equivalent to ``-o``.
:param o: :class:`py.object`
:returns: :class:`py.object`
.. function:: py.PY_positive(o)
Returns the "positive" of ``o``, equivalent to ``+o``.
:param o: :class:`py.object`
:returns: :class:`py.object`
.. [#kwonly] 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.
.. [#star-args] due to this and contrary to Python 2, py.js allows
arguments other than ``**kwargs`` to follow ``*args``.
.. _PyArg_ParseTupleAndKeywords:
http://docs.python.org/c-api/arg.html#PyArg_ParseTupleAndKeywords
|
