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
- 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
SLOTS = [
# typeobject
Slot("__new__", "tp$new", "new"),
Slot("__init__", "tp$init", "init"),
Slot("__str__", "tp$print", "print"),
Slot("__repr__", "$r", "repr",
opcode="UNARY_CONVERT"),
Slot("__hash__", "tp$hash", "hash"), # can be None or a function
Slot("__call__", "tp$call", "call"),
# Note: In CPython, if tp$getattro exists, tp$getattr is never called.
Slot("__getattribute__", "tp$getattr", "getattr"),
Slot("__getattr__", "tp$getattr", "getattr"),
Slot("__setattr__", "tp$setattr", "setattr"),
Slot("__delattr__", "tp$setattr", "setattr"),
# 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"),
# Skulpt currently has no support for this slot
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__", "ob$lt", "richcmpfunc"),
Slot("__le__", "ob$le", "richcmpfunc"),
Slot("__eq__", "ob$eq", "richcmpfunc"),
Slot("__ne__", "ob$ne", "richcmpfunc"),
Slot("__gt__", "ob$gt", "richcmpfunc"),
Slot("__ge__", "ob$ge", "richcmpfunc"),
# number
# to indicate a number set tp$as_number = true
# 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$reflected_multiply", "binary_nb", index=1),
Slot("__div__", "nb$divide", "binary_nb", index=0,
opcode="BINARY_DIVIDE"),
Slot("__rdiv__", "nb$reflected_divide", "binary_nb", index=1),
Slot("__mod__", "nb$remainder", "binary_nb", index=0,
opcode="BINARY_MODULO"),
Slot("__rmod__", "nb$reflected_remainder", "binary_nb", index=1),
Slot("__divmod__", "nb$divmod", "binary_nb", index=0),
Slot("__rdivmod__", "nb$reflected_divmod", "binary_nb", index=1),
Slot("__lshift__", "nb$lshift", "binary_nb", index=0,
opcode="BINARY_LSHIFT"),
Slot("__rlshift__", "nb$reflected_lshift", "binary_nb", index=1),
Slot("__rshift__", "nb$rshift", "binary_nb", index=0,
opcode="BINARY_RSHIFT"),
Slot("__rrshift__", "nb$reflected_rshift", "binary_nb", index=1),
Slot("__and__", "nb$and", "binary_nb", index=0,
opcode="BINARY_AND"),
Slot("__rand__", "nb$reflected_and", "binary_nb", index=1),
Slot("__xor__", "nb$xor", "binary_nb", index=0,
opcode="BINARY_XOR"),
Slot("__rxor__", "nb$reflected_xor", "binary_nb", index=1),
Slot("__or__", "nb$or", "binary_nb", index=0,
opcode="BINARY_OR"),
Slot("__ror__", "nb$reflected_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$reflected_floor_divide", "binary_nb", index=1),
# in skulpt we reuse the nb$divide slot - Cpython has an nb$true_divide slot
Slot("__truediv__", "nb$divide", "binary_nb", index=0,
opcode="BINARY_TRUE_DIVIDE"),
Slot("__rtruediv__", "nb$reflected_divide", "binary_nb", index=1),
Slot("__pow__", "nb$power", "ternary",
opcode="BINARY_POWER"),
Slot("__rpow__", "nb$reflected_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$abs", "unary"),
Slot("__nonzero__", "nb$bool", "inquiry"), # inverse of UNARY_NOT opcode - python 2 only
Slot("__bool__", "nb$bool", "inquiry"), # inverse of UNARY_NOT opcode - python 3 only
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__: Skulpt uses sq$length
# __delitem__: Reuses __setitem__ slot.
# to indicate a mapping set tp$as_sequence_or_mapping = true
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__", "sq$length", "len"),
# sequence
# to indicate a sequence set tp$as_sequence_or_mapping = true
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"),
# unlike Cpython Skulpt reuses the mapping slots
Slot("__getitem__", "mp$subscript", "sq$item",
opcode="BINARY_SUBSCR"),
Slot("__setitem__", "mp$ass_subscript", ""),
Slot("__delitem__", "mp$ass_subscript", "sq$delitem"),
# slices are passed as explicit slice objects to mp$subscript.
# these are not used in skulpt and are depreciated in python 3
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