The Skulpt Reference Manual
---------------------------
It would take a bit of research and work but I also wonder if there is not a subset of other skulpt functions that could be collected together more nicely as the skulpt internal api.
This could or should probably more closely follow the C API defined by CPython. https://docs.python.org/2/c-api/index.html
Although the more I think about it the more I think we just need to do a better job of providing some organized documentation. I've started an outline, and I think if we can get a decent outline and agree on some general principles for development we could actually document Skulpt and make it much more accessible for people to help.
- Terminology
- "Python objects" versus "Javascript objects"
- Sk.builtin
- Sk.misceval
- Sk.ffi
- Sk.abstr
- slot functions
- builtin functions
- magic methods
- Standard Data Type Interfaces
- Checking types
- Checking argument types Sk.builtin.pyCheckType -- weird function that takes one of the below as an argument
- Sk.builtin.checkNumber
- Sk.builtin.checkComplex
- Sk.builtin.checkInt
- Sk.builtin.checkString
- Sk.builtin.checkClass
- Sk.builtin.checkBool
- Sk.builtin.checkNone
- Sk.builtin.checkFunction
- Sk.builtin.checkIterable
- Sk.builtin.checkCallable
- Sk.builtin.checkSequence
- Common
- Determining if an object is iterable
- General Sequence and slicing operators (many Sk.abstr functions)
- lists
- dictionaries
- sets
- integers/longs
- floats
- complex
- boolean
- Exceptions
- None
- Operators
- binary operators
- unary
- Dunder methods
- the builtin names tp$xxx, nb$xxx, sq$xxxx
- mapping to the __ names
- creating a class
- building a class Sk.misceval.buildClass
- Iteration
- Getting an interator
- iterating with an iterator
- Comparing
- richCompareBool
- isTrue
- functions — callable from Python
- The function wrapper Sk.builtin.func -- meant to be called ``new Sk.builtin.func(javascriptfunc)``
- calling a Python function from Javascript
- named arguments
- *args
- **kwargs
- creating a module
- module template
- exposing functions from the module
- exposing constants
- creating classes in a module
- To Javascript and Back to Python
- The Sk.ffi interface
- Utility functions
- Checking argument counts Sk.builtin.pyCheckArgs
- Importing and Running code
- Running source from a string
- importing a module/package
-
- Functions for working with Python Objects
The abstr namespace defines a bunch of functions that you should use when working with Python objects.
- Sk.abstr.typeName = function (v)
- Sk.abstr.binop_type_error = function (v, w, name)
- Sk.abstr.unop_type_error = function (v, name)
- Sk.abstr.boNameToSlotFuncLhs_ = function (obj, name)
- Sk.abstr.boNameToSlotFuncRhs_ = function (obj, name)
- Sk.abstr.iboNameToSlotFunc_ = function (obj, name)
- Sk.abstr.uoNameToSlotFunc_ = function (obj, name)
- Sk.abstr.binary_op_ = function (v, w, opname)
- Sk.abstr.binary_iop_ = function (v, w, opname)
- Sk.abstr.unary_op_ = function (v, opname)
- Sk.abstr.numOpAndPromote = function (a, b, opfn)
- Sk.abstr.boNumPromote_ =
- Sk.abstr.numberBinOp = function (v, w, op)
- Sk.abstr.numberInplaceBinOp = function (v, w, op)
- Sk.abstr.numberUnaryOp = function (v, op)
- Sk.abstr.fixSeqIndex_ = function (seq, i)
- Sk.abstr.sequenceContains = function (seq, ob)
- Sk.abstr.sequenceConcat = function (seq1, seq2)
- Sk.abstr.sequenceGetIndexOf = function (seq, ob)
- Sk.abstr.sequenceGetCountOf = function (seq, ob)
- Sk.abstr.sequenceGetItem = function (seq, i, canSuspend)
- Sk.abstr.sequenceSetItem = function (seq, i, x, canSuspend)
- Sk.abstr.sequenceDelItem = function (seq, i)
- Sk.abstr.sequenceRepeat = function (f, seq, n)
- Sk.abstr.sequenceGetSlice = function (seq, i1, i2)
- Sk.abstr.sequenceDelSlice = function (seq, i1, i2)
- Sk.abstr.sequenceSetSlice = function (seq, i1, i2, x)
- Sk.abstr.sequenceUnpack = function (seq, n)
- Sk.abstr.objectFormat = function (obj, format_spec)
- Sk.abstr.objectAdd = function (a, b)
- Sk.abstr.objectNegative = function (obj)
- Sk.abstr.objectPositive = function (obj)
- Sk.abstr.objectDelItem = function (o, key)
- Sk.abstr.objectGetItem = function (o, key, canSuspend)
- Sk.abstr.objectSetItem = function (o, key, v, canSuspend)
- Sk.abstr.gattr = function (obj, nameJS, canSuspend)
- Sk.abstr.sattr = function (obj, nameJS, data, canSuspend)
- Sk.abstr.iter = function (obj)
- Sk.abstr.iternext = function (it, canSuspend)
Sk.misceval
Misc
* Sk.misceval.Suspension = function Suspension(resume, child, data)
* Sk.misceval.retryOptionalSuspensionOrThrow = function (susp, message)
* Sk.misceval.isIndex = function (o)
* Sk.misceval.asIndex = function (o)
* Sk.misceval.applySlice = function (u, v, w, canSuspend)
* Sk.misceval.assignSlice = function (u, v, w, x, canSuspend)
* Sk.misceval.arrayFromArguments = function (args)
* Sk.misceval.swappedOp_ =
* Sk.misceval.richCompareBool = function (v, w, op)
* Sk.misceval.objectRepr = function (v)
* Sk.misceval.opAllowsEquality = function (op)
* Sk.misceval.isTrue = function (x)
* Sk.misceval.softspace_ = fals
* Sk.misceval.print_ = function (x)
* Sk.misceval.loadname = function (name, other)
* Sk.misceval.call = function (func, kwdict, varargseq, kws, args)
* Sk.misceval.callAsync = function (suspensionHandlers, func, kwdict, varargseq, kws, args)
* Sk.misceval.callOrSuspend = function (func, kwdict, varargseq, kws, args)
* Sk.misceval.callsim = function (func, args)
* Sk.misceval.callsimAsync = function (suspensionHandlers, func, args)
* Sk.misceval.callsimOrSuspend = function (func, args)
* Sk.misceval.apply = function (func, kwdict, varargseq, kws, args)
* Sk.misceval.asyncToPromise = function(suspendablefn, suspHandlers)
* Sk.misceval.applyAsync = function (suspHandlers, func, kwdict, varargseq, kws, args)
* Sk.misceval.chain = function (initialValue, chainedFns)
* Sk.misceval.applyOrSuspend = function (func, kwdict, varargseq, kws, args)
* Sk.misceval.buildClass = function (globals, func, name, bases)
- Understanding the mapping from Skupt api functions to dunder methods
.. code-block:: python
SLOTS = [
# typeobject
Slot("__new__", "tp$new", "new"),
Slot("__init__", "tp$init", "init"),
Slot("__str__", "tp$print", "print"),
Slot("__repr__", "tp$repr", "repr",
opcode="UNARY_CONVERT"),
Slot("__hash__", "tp$hash", "hash"),
Slot("__call__", "tp$call", "call"),
# Note: In CPython, if tp$getattro exists, tp$getattr is never called.
Slot("__getattribute__", "tp$getattro", "getattro"),
Slot("__getattr__", "tp$getattro", "getattro"),
Slot("__setattr__", "tp$setattro", "setattro"),
Slot("__delattr__", "tp$setattro", "setattro"),
# for Py_TPFLAGS_HAVE_ITER:
Slot("__iter__", "tp$iter", "unary"),
Slot("next", "tp$iternext", "next", python_version="2"),
Slot("__next__", "tp$iternext", "next", python_version="3"),
# for Py_TPFLAGS_HAVE_CLASS:
Slot("__get__", "tp$descr_get", "descr_get"),
Slot("__set__", "tp$descr_set", "descr_set"),
Slot("__delete__", "tp$descr_set", "descr_delete"),
Slot("__del__", "tp$del", "destructor"),
# all typically done by __richcompare__
Slot("__cmp$_", "tp$compare", "cmp",
python_version="2"), # "tp$reserved" in Python 3
Slot("__lt__", "tp$richcompare", "richcmpfunc"),
Slot("__le__", "tp$richcompare", "richcmpfunc"),
Slot("__eq__", "tp$richcompare", "richcmpfunc"),
Slot("__ne__", "tp$richcompare", "richcmpfunc"),
Slot("__gt__", "tp$richcompare", "richcmpfunc"),
Slot("__ge__", "tp$richcompare", "richcmpfunc"),
Slot("__richcompare__", "tp$richcompare", "richcmpfunc"),
# number methods:
Slot("__add__", "nb$add", "binary_nb", index=0,
opcode="BINARY_ADD"),
Slot("__radd__", "nb$add", "binary_nb", index=1),
Slot("__sub__", "nb$subtract", "binary_nb", index=0,
opcode="BINARY_SUBTRACT"),
Slot("__rsub__", "nb$subtract", "binary_nb", index=1),
Slot("__mul__", "nb$multiply", "binary_nb", index=0),
Slot("__rmul__", "nb$multiply", "binary_nb", index=1),
Slot("__div__", "nb$divide", "binary_nb", index=0,
opcode="BINARY_DIVIDE"),
Slot("__rdiv__", "nb$divide", "binary_nb", index=1),
Slot("__mod__", "nb$remainder", "binary_nb", index=0,
opcode="BINARY_MODULO"),
Slot("__rmod__", "nb$remainder", "binary_nb", index=1),
Slot("__divmod__", "nb$divmod", "binary_nb", index=0),
Slot("__rdivmod__", "nb$divmod", "binary_nb", index=1),
Slot("__lshift__", "nb$lshift", "binary_nb", index=0,
opcode="BINARY_LSHIFT"),
Slot("__rlshift__", "nb$lshift", "binary_nb", index=1),
Slot("__rshift__", "nb$rshift", "binary_nb", index=0,
opcode="BINARY_RSHIFT"),
Slot("__rrshift__", "nb$rshift", "binary_nb", index=1),
Slot("__and__", "nb$and", "binary_nb", index=0,
opcode="BINARY_AND"),
Slot("__rand__", "nb$and", "binary_nb", index=1),
Slot("__xor__", "nb$xor", "binary_nb", index=0,
opcode="BINARY_XOR"),
Slot("__rxor__", "nb$xor", "binary_nb", index=1),
Slot("__or__", "nb$or", "binary_nb", index=0,
opcode="BINARY_OR"),
Slot("__ror__", "nb$or", "binary_nb", index=1),
# needs Py_TPFLAGS_HAVE_CLASS:
Slot("__floordiv__", "nb$floor_divide", "binary_nb", index=0,
opcode="BINARY_FLOOR_DIVIDE"),
Slot("__rfloordiv__", "nb$floor_divide", "binary_nb", index=1),
Slot("__truediv__", "nb$true_divide", "binary_nb", index=0,
opcode="BINARY_TRUE_DIVIDE"),
Slot("__rtruediv__", "nb$true_divide", "binary_nb", index=1),
Slot("__pow__", "nb$power", "ternary",
opcode="BINARY_POWER"),
Slot("__rpow__", "nb$power", "ternary"), # needs wrap_tenary_nb
Slot("__neg__", "nb$negative", "unary",
opcode="UNARY_NEGATIVE"),
Slot("__pos__", "nb$positive", "unary",
opcode="UNARY_POSITIVE"),
Slot("__abs__", "nb$absolute", "unary"),
Slot("__nonzero__", "nb$nonzero", "inquiry"), # inverse of UNARY_NOT opcode
Slot("__invert__", "nb$invert", "unary",
opcode="UNARY_INVERT"),
Slot("__coerce__", "nb$coerce", "coercion"), # not needed
Slot("__int__", "nb$int", "unary"), # expects exact int as return
Slot("__long__", "nb$long", "unary"), # expects exact long as return
Slot("__float__", "nb$float", "unary"), # expects exact float as return
Slot("__oct__", "nb$oct", "unary"),
Slot("__hex__", "nb$hex", "unary"),
# Added in 2.0. These are probably largely useless.
# (For list concatenation, use sl_inplace_concat)
Slot("__iadd__", "nb$inplace_add", "binary",
opcode="INPLACE_ADD"),
Slot("__isub__", "nb$inplace_subtract", "binary",
opcode="INPLACE_SUBTRACT"),
Slot("__imul__", "nb$inplace_multiply", "binary",
opcode="INPLACE_MULTIPLY"),
Slot("__idiv__", "nb$inplace_divide", "binary",
opcode="INPLACE_DIVIDE"),
Slot("__imod__", "nb$inplace_remainder", "binary",
opcode="INPLACE_MODULO"),
Slot("__ipow__", "nb$inplace_power", "ternary",
opcode="INPLACE_POWER"),
Slot("__ilshift__", "nb$inplace_lshift", "binary",
opcode="INPLACE_LSHIFT"),
Slot("__irshift__", "nb$inplace_rshift", "binary",
opcode="INPLACE_RSHIFT"),
Slot("__iand__", "nb$inplace_and", "binary",
opcode="INPLACE_AND"),
Slot("__ixor__", "nb$inplace_xor", "binary",
opcode="INPLACE_XOR"),
Slot("__ior__", "nb$inplace_or", "binary",
opcode="INPLACE_OR"),
Slot("__ifloordiv__", "nb$inplace_floor_divide", "binary",
opcode="INPLACE_FLOOR_DIVIDE"),
Slot("__itruediv__", "nb$inplace_true_divide", "binary",
opcode="INPLACE_TRUE_DIVIDE"),
# Added in 2.5. Used whenever i acts as a sequence index (a[i])
Slot("__index__", "nb$index", "unary"), # needs int/long return
# mapping
# __getitem__: Python first tries mp$subscript, then sq$item
# __len__: Python first tries sq$length, then mp$length
# __delitem__: Reuses __setitem__ slot.
Slot("__getitem__", "mp$subscript", "binary",
opcode="BINARY_SUBSCR"),
Slot("__delitem__", "mp$ass_subscript", "objobjargproc", index=0),
Slot("__setitem__", "mp$ass_subscript", "objobjargproc", index=1),
Slot("__len__", "mp$length", "len"),
# sequence
Slot("__contains__", "sq$contains", "objobjproc"),
# These sequence methods are duplicates of number or mapping methods.
# For example, in the C API, "add" can be implemented either by sq$concat,
# or by np_add. Python will try both. The opcode mapping is identical
# between the two. So e.g. the implementation of the BINARY_SUBSCR opcode in
# Python/ceval.c will try both sq$item and mp$subscript, which is why this
# opcode appears twice in our list.
Slot("__add__", "sq$concat", "binary",
opcode="BINARY_ADD"),
Slot("__mul__", "sq$repeat", "indexargfunc",
opcode="BINARY_MULTIPLY"),
Slot("__iadd__", "sq$inplace_concat", "binary",
opcode="INPLACE_ADD"),
Slot("__imul__", "sq$inplace_repeat", "indexargfunc",
opcode="INPLACE_MUL"),
Slot("__getitem__", "sq$item", "sq$item",
opcode="BINARY_SUBSCR"),
Slot("__setitem__", "sq$ass_slice", "sq$ass_item"),
Slot("__delitem__", "sq$ass_item", "sq$delitem"),
# slices are passed as explicit slice objects to mp$subscript.
Slot("__getslice__", "sq$slice", "sq$slice"),
Slot("__setslice__", "sq$ass_slice", "ssizessizeobjarg"),
Slot("__delslice__", "sq$ass_slice", "delslice"),
]
This list may or may not be complete it comes from: https://github.com/google/pytypedecl/blob/master/slots.py