[GR-13361] module docstring

PullRequest: graalpython/356

Author: cosminbasca

graalpython/com.oracle.graal.python.test/src/tests/package/__init__.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # The Universal Permissive License (UPL), Version 1.0
@@ -37,5 +37,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+"""PACKAGE DOC"""
+
 from . import moduleY
 print("after importing moduleY")

graalpython/com.oracle.graal.python.test/src/tests/package/moduleA.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # The Universal Permissive License (UPL), Version 1.0
@@ -37,4 +37,6 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+"""MODULE A DOC"""
+
 print("module A")

graalpython/com.oracle.graal.python.test/src/tests/test_imports.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # The Universal Permissive License (UPL), Version 1.0
@@ -51,6 +51,13 @@ def test_relative_import():
         raise e
 
 
+def test_module_docstring():
+    import package
+    assert package.__doc__ == "PACKAGE DOC"
+    from package import moduleA
+    assert moduleA.__doc__ == "MODULE A DOC"
+
+
 def test_dotted_import():
     # this is to prevent ides from optimising out the unused import
     try:

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/ModuleRootNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2018, Oracle and/or its affiliates.
+ * Copyright (c) 2017, 2019, Oracle and/or its affiliates.
  * Copyright (c) 2013, Regents of the University of California
  *
  * All rights reserved.
@@ -27,27 +27,45 @@
 
 import com.oracle.graal.python.PythonLanguage;
 import com.oracle.graal.python.nodes.expression.ExpressionNode;
+import com.oracle.graal.python.nodes.frame.WriteGlobalNode;
 import com.oracle.truffle.api.CompilerAsserts;
+import com.oracle.truffle.api.CompilerDirectives;
 import com.oracle.truffle.api.frame.FrameDescriptor;
 import com.oracle.truffle.api.frame.FrameSlot;
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.source.SourceSection;
 
+import static com.oracle.graal.python.nodes.SpecialAttributeNames.__DOC__;
+
 public class ModuleRootNode extends PClosureRootNode {
 
     private final String name;
+    private final String doc;
 
     @Child private ExpressionNode body;
+    @Child private WriteGlobalNode writeModuleDoc;
 
-    public ModuleRootNode(PythonLanguage language, String name, ExpressionNode file, FrameDescriptor descriptor, FrameSlot[] freeVarSlots) {
+    public ModuleRootNode(PythonLanguage language, String name, String doc, ExpressionNode file, FrameDescriptor descriptor, FrameSlot[] freeVarSlots) {
         super(language, descriptor, freeVarSlots);
         this.name = "<module '" + name + "'>";
+        this.doc = doc;
         this.body = file;
     }
 
+    private WriteGlobalNode getWriteModuleDoc() {
+        if (writeModuleDoc == null) {
+            CompilerDirectives.transferToInterpreterAndInvalidate();
+            writeModuleDoc = insert(WriteGlobalNode.create(__DOC__));
+        }
+        return writeModuleDoc;
+    }
+
     @Override
     public Object execute(VirtualFrame frame) {
         addClosureCellsToLocals(frame);
+        if (doc != null) {
+            getWriteModuleDoc().doWrite(frame, doc);
+        }
         return body.execute(frame);
     }
 
@@ -66,6 +84,10 @@ public String getName() {
         return name;
     }
 
+    public String getDoc() {
+        return doc;
+    }
+
     @Override
     public SourceSection getSourceSection() {
         return body.getSourceSection();

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/NodeFactory.java

@@ -132,9 +132,9 @@ public <T> T duplicate(Node orig, Class<T> clazz) {
         return (T) NodeUtil.cloneNode(orig);
     }
 
-    public ModuleRootNode createModuleRoot(String name, ExpressionNode file, FrameDescriptor fd) {
+    public ModuleRootNode createModuleRoot(String name, String doc, ExpressionNode file, FrameDescriptor fd) {
         file.markAsRoot();
-        return new ModuleRootNode(language, name, file, fd, null);
+        return new ModuleRootNode(language, name, doc, file, fd, null);
     }
 
     public FunctionRootNode createFunctionRoot(SourceSection sourceSection, String functionName, boolean isGenerator, FrameDescriptor frameDescriptor, ExpressionNode body,

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/parser/PythonTreeTranslator.java

@@ -232,7 +232,7 @@ public Object visitFile_input(Python3Parser.File_inputContext ctx) {
         ExpressionNode file = asExpression(super.visitFile_input(ctx));
         deriveSourceSection(ctx, file);
         environment.popScope();
-        return factory.createModuleRoot(name, file, ctx.scope.getFrameDescriptor());
+        return factory.createModuleRoot(name, getModuleDoc(ctx), file, ctx.scope.getFrameDescriptor());
     }
 
     @Override
@@ -256,10 +256,34 @@ public Object visitSingle_input(Python3Parser.Single_inputContext ctx) {
         if (isInlineMode) {
             return body;
         } else {
-            return factory.createModuleRoot("<expression>", body, ctx.scope.getFrameDescriptor());
+            return factory.createModuleRoot("<expression>", getModuleDoc(ctx), body, ctx.scope.getFrameDescriptor());
         }
     }
 
+    private String getModuleDoc(ParserRuleContext ctx) {
+        Python3Parser.Simple_stmtContext firstStatement = null;
+        if (ctx instanceof Python3Parser.Single_inputContext) {
+            firstStatement = ((Python3Parser.Single_inputContext) ctx).simple_stmt();
+        } else if (ctx instanceof Python3Parser.File_inputContext) {
+            List<Python3Parser.StmtContext> stmt = ((Python3Parser.File_inputContext) ctx).stmt();
+            if (!stmt.isEmpty()) {
+                firstStatement = stmt.get(0).simple_stmt();
+            }
+        }
+
+        if (firstStatement != null) {
+            try {
+                PNode stringNode = parseString(new String[]{firstStatement.getText().trim()});
+                if (stringNode instanceof StringLiteralNode) {
+                    return ((StringLiteralNode) stringNode).getValue();
+                }
+            } catch (Exception ignored) {
+                // not a string literal
+            }
+        }
+        return null;
+    }
+
     @Override
     public Object visitAtom_expr(Python3Parser.Atom_exprContext ctx) {
         // TODO: deal with AWAIT