Merge branch 'master' into tests/add-attr-and-descriptor-tests

Author: bnmnetp

src/compile.js

@@ -2066,6 +2066,13 @@ Compiler.prototype.buildcodeobj = function (n, coname, decorator_list, args, cal
         out(scopename, ".co_varnames=[];");
     }
 
+    //
+    // Skulpt doesn't have "co_consts", so record the docstring (or
+    // None) in the "co_docstring" property of the code object, ready
+    // for use by the Sk.builtin.func constructor.
+    //
+    out(scopename, ".co_docstring=", this.cDocstringOfCode(n), ";");
+
     //
     // attach flags
     //
@@ -2115,7 +2122,6 @@ Compiler.prototype.buildcodeobj = function (n, coname, decorator_list, args, cal
                             "\",arguments.length,0,0);return new Sk.builtins['generator'](", scopename, ",$gbl,[]", frees, ");}))");
         }
     } else {
-        var res;
         if (decos.length > 0) {
             out("$ret = new Sk.builtins['function'](", scopename, ",$gbl", frees, ");");
             for (let decorator of decos.reverse()) {
@@ -2129,6 +2135,47 @@ Compiler.prototype.buildcodeobj = function (n, coname, decorator_list, args, cal
     }
 };
 
+/** JavaScript for the docstring of the given body, or null if the
+ * body has no docstring.
+ */
+Compiler.prototype.maybeCDocstringOfBody = function(body) {
+    if (body.length === 0)  // Don't think this can happen?
+        return null;
+
+    const stmt_0 = body[0];
+    if (stmt_0.constructor !== Sk.astnodes.Expr)
+        return null;
+
+    const expr = stmt_0.value;
+    if (expr.constructor !== Sk.astnodes.Str)
+        return null;
+
+    return this.vexpr(expr);
+};
+
+/** JavaScript for the docstring of the given node.  Only called from
+ * buildcodeobj(), and expects a FunctionDef, Lambda, or GeneratorExp
+ * node.  We give a "None" docstring to a GeneratorExp node, although
+ * it is not carried over to the final generator; this is harmless.
+ */
+Compiler.prototype.cDocstringOfCode = function(node) {
+    switch (node.constructor) {
+    case Sk.astnodes.AsyncFunctionDef:  // For when it's supported
+    case Sk.astnodes.FunctionDef:
+        return (
+            this.maybeCDocstringOfBody(node.body)
+            || "Sk.builtin.none.none$"
+        );
+
+    case Sk.astnodes.Lambda:
+    case Sk.astnodes.GeneratorExp:
+        return "Sk.builtin.none.none$";
+
+    default:
+        Sk.asserts.fail(`unexpected node kind ${node.constructor.name}`);
+    }
+}
+
 Compiler.prototype.cfunction = function (s, class_for_super) {
     var funcorgen;
     Sk.asserts.assert(s instanceof Sk.astnodes.FunctionDef);
@@ -2669,8 +2716,19 @@ Compiler.prototype.exitScope = function () {
  * @param {Sk.builtin.str=} class_for_super
  */
 Compiler.prototype.cbody = function (stmts, class_for_super) {
-    var i;
-    for (i = 0; i < stmts.length; ++i) {
+    var i = 0;
+
+    // If we have a docstring, then assign it to __doc__, and skip over
+    // the expression when properly compiling the rest of the body.  This
+    // happens for class and module bodies.
+    //
+    const maybeDocstring = this.maybeCDocstringOfBody(stmts);
+    if (maybeDocstring !== null) {
+        out("$loc.__doc__ = ", maybeDocstring, ";");
+        i = 1;
+    }
+
+    for (; i < stmts.length; ++i) {
         this.vstmt(stmts[i], class_for_super);
     }
 };

src/function.js

@@ -34,7 +34,7 @@ Sk.builtin.func = Sk.abstr.buildNativeClass("function", {
 
         this.$name = (code.co_name && code.co_name.v) || code.name || "<native JS>";
         this.$d = Sk.builtin.dict ? new Sk.builtin.dict() : undefined;
-        this.$doc = code.$doc;
+        this.$doc = code.co_docstring || Sk.builtin.none.none$;
         this.$module = (Sk.globals && Sk.globals["__name__"]) || Sk.builtin.none.none$;
         this.$qualname = (code.co_qualname && code.co_qualname.v) || this.$name;
 
@@ -127,7 +127,13 @@ Sk.builtin.func = Sk.abstr.buildNativeClass("function", {
         },
         __doc__: {
             $get() {
-                return new Sk.builtin.str(this.$doc);
+                return this.$doc;
+            },
+            $set(v) {
+                // The value the user is setting __doc__ to can be any Python
+                // object.  If we receive 'undefined' then the user is deleting
+                // __doc__, which is allowed and results in __doc__ being None.
+                this.$doc = v || Sk.builtin.none.none$;
             },
         },
     },

test/unit3/copydocstring.py

@@ -0,0 +1,3 @@
+"""Copy docstring"""
+
+doc = __doc__

test/unit3/overwritedocstring.py

@@ -0,0 +1,3 @@
+"""First docstring"""
+
+__doc__ = "Second docstring"

test/unit3/test_docstring.py

@@ -0,0 +1,162 @@
+import unittest
+
+
+def banana():
+    "Yellow"
+    return 42
+
+
+def orange():
+    "Oran" "ge"
+
+
+def blackbirds():
+    4 + 20  # Not a docstring
+
+
+def do_nothing():
+    pass
+
+
+def make_adder(n):
+    "Function adding N"
+    def add(x):
+        "Compute N + X"
+        return n + x
+    return add
+
+
+class Strawberry:
+    "Delicious"
+    doc = __doc__
+
+    def weight(self):
+        "Heavy"
+        return 0.25
+
+    @classmethod
+    def is_red(cls):
+        "Very red"
+        return True
+
+    @staticmethod
+    def pick():
+        "Picked"
+        return None
+
+
+class Tangerine:
+    def peel():
+        pass
+
+
+class Pear:
+    "This will not be the __doc__"
+    __doc__ = "Conference"
+
+
+class TestDocstrings(unittest.TestCase):
+    def test_builtin(self):
+        self.assertTrue(divmod.__doc__.startswith("Return the tuple (x//y, x%y)"))
+
+    def test_library_function(self):
+        # This test will need updating if/when random.seed gets a docstring.
+        # It also fails under cpython.
+        import random
+        self.assertEqual(random.seed.__doc__, None)
+
+    def test_function(self):
+        self.assertEqual(banana.__doc__, "Yellow")
+        self.assertEqual(orange.__doc__, "Orange")
+        self.assertEqual(make_adder.__doc__, "Function adding N")
+
+    def test_runtime_function(self):
+        self.assertEqual(make_adder(3).__doc__, "Compute N + X")
+
+    def test_non_string_expr(self):
+        self.assertEqual(blackbirds.__doc__, None)
+
+    def test_no_expr(self):
+        self.assertEqual(do_nothing.__doc__, None)
+
+    def test_class(self):
+        self.assertEqual(Strawberry.__doc__, "Delicious")
+        self.assertEqual(Strawberry.doc, "Delicious")
+
+    def test_class_no_docstring(self):
+        self.assertEqual(Tangerine.__doc__, None)
+        self.assertEqual(Tangerine.peel.__doc__, None)
+        self.assertEqual(Tangerine().peel.__doc__, None)
+
+    def test_class_explicit_docstring(self):
+        self.assertEqual(Pear.__doc__, "Conference")
+
+    def test_method(self):
+        self.assertEqual(Strawberry.weight.__doc__, "Heavy")
+        s = Strawberry()
+        self.assertEqual(s.weight.__doc__, "Heavy")
+
+    def test_classmethod(self):
+        self.assertEqual(Strawberry.is_red.__doc__, "Very red")
+
+    def test_staticmethod(self):
+        self.assertEqual(Strawberry.pick.__doc__, "Picked")
+
+    def test_module(self):
+        import bisect
+        self.assertEqual(bisect.__doc__, "Bisection algorithms.")
+
+    def test_local_module(self):
+        import copydocstring
+        self.assertEqual(copydocstring.__doc__, "Copy docstring")
+        self.assertEqual(copydocstring.doc, "Copy docstring")
+
+    def test_local_module_overwriting_docstring(self):
+        import overwritedocstring
+        self.assertEqual(overwritedocstring.__doc__, "Second docstring")
+
+    def test_lambda(self):
+        f = lambda x: 42
+        self.assertEqual(f.__doc__, None)
+
+    def test_setting_on_function(self):
+        def f():
+            "hello"
+            return 42
+
+        self.assertEqual(f.__doc__, "hello")
+
+        f.__doc__ = "world"
+        self.assertEqual(f.__doc__, "world")
+
+        # Setting to a non-string is odd but allowed:
+        f.__doc__ = 42
+        self.assertEqual(f.__doc__, 42)
+
+        # Attemping to delete __doc__ instead sets it to None:
+        del f.__doc__
+        self.assertEqual(f.__doc__, None)
+
+    def test_setting_on_method(self):
+        class Banana:
+            def peel(self):
+                "Remove peel"
+                pass
+
+        self.assertEqual(Banana.peel.__doc__, "Remove peel")
+
+        # We can set the doc when accessed on the class:
+        Banana.peel.__doc__ = "Take out of peel"
+        self.assertEqual(Banana.peel.__doc__, "Take out of peel")
+
+        # But not when accessed via an instance:
+
+        def set_on_method_of_instance():
+            banana = Banana()
+            banana.peel.__doc__ = "this will not work"
+
+        self.assertRaises(AttributeError, set_on_method_of_instance)
+
+
+if __name__ == '__main__':
+    unittest.main()