[GR-15433] Adopt terminology

PullRequest: graalpython/493

Author: timfel

CHANGELOG.md

@@ -3,6 +3,10 @@
 This changelog summarizes major changes between GraalVM versions of the Python
 language runtime. The main focus is on user-observable behavior of the engine.
 
+## Version 1.0.0 RC16
+
+* No user-facing changes
+
 ## Version 1.0.0 RC15
 
 * Implement PEP 487 `__init_subclass__`

CONTRIBUTING.md

@@ -1,11 +1,11 @@
-# Graal/Truffle-based implementation of Python
+# GraalVM Implementation of Python
 
-GraalVM provides an early-stage experimental implementation of Python. A primary
-goal is to support SciPy and its constituent libraries. This Python
-implementation currently aims to be compatible with Python 3.7, but it is a long
-way from there, and it is very likely that any Python program that requires any
-imports at all will hit something unsupported. At this point, the Python
-implementation is made available for experimentation and curious end-users.
+This is an early-stage experimental implementation of Python. A primary goal is
+to support SciPy and its constituent libraries. This Python implementation
+currently aims to be compatible with Python 3.7, but it is a long way from
+there, and it is very likely that any Python program that requires any packages
+at all will hit something unsupported. At this point, the Python implementation
+is made available for experimentation and curious end-users.
 
 ### Trying it
 
@@ -38,18 +38,35 @@ dependencies), you should be able to `import numpy` afterwards.
 
 Support for more extension modules is high priority for us. We are actively
 building out our support for the Python C API to make extensions such as NumPy,
-SciPy, Scikit-learn, Tensorflow and the like work. This work means that some
-other extensions might also already work, but we're not actively testing other
-extensions right now and cannot promise anything. Note that to try extensions on
-this implementation, you have to download, build, and install them manually for
-now. To do so, we recommend LLVM 6. Other versions might also work, but this
-version is what we're testing with in our CI.
+SciPy, Scikit-learn, Pandas, Tensorflow and the like work. This work means that
+some other extensions might also already work, but we're not actively testing
+other extensions right now and cannot promise anything. Note that to try
+extensions on this implementation, you have to download, build, and install them
+manually for now. To do so, we recommend LLVM 6. Other versions might also work,
+but this version is what we're testing with in our CI.
+
+### Polyglot Usage
+
+We have a [document](doc/INTEROP.md) describing how we implement the
+cross-language interop. This will hopefully give you an idea how to use it.
+
+### Contributing
+
+I you're thinking about contributing something to this repository, you will need
+to sign the [Oracle Contributor
+Agreement](http://www.graalvm.org/community/contributors/) for us to able to
+merge your work. Please also take note of our [code of
+conduct](http://www.graalvm.org/community/conduct/) for contributors.
+
+To get you started, we have [written](docs/CONTRIBUTING.md) a bit about the
+structure of this interpreter that should show how to fix things or add
+features.
 
 ### Licensing
 
-This Graal/Truffle-based implementation of Python is copyright (c) 2017, 2018
-Oracle and/or its affiliates and is made available to you under the terms the
-Universal Permissive License v 1.0 as shown at
+This GraalVM implementation of Python is copyright (c) 2017, 2019 Oracle and/or
+its affiliates and is made available to you under the terms the Universal
+Permissive License v 1.0 as shown at
 [http://oss.oracle.com/licenses/upl](http://oss.oracle.com/licenses/upl). This
 implementation is in part derived from and contains additional code from 3rd
 parties, the copyrights and licensing of which is detailed in the

README.md

@@ -0,0 +1,81 @@
+### Contributing to the GraalVM Implementation of Python
+
+Thanks for considering to contribute! To get you started, here is a bit of
+information about the structure of this implementation.
+
+##### But first...
+
+You will need to sign the [Oracle Contributor
+Agreement](http://www.graalvm.org/community/contributors/) for us to be able to
+merge your work.
+
+Please also take some time to review our [code of
+conduct](http://www.graalvm.org/community/conduct/) for contributors.
+
+##### Getting started
+
+The first thing you want to do is to set up
+[mx](https://github.com/graalvm/mx.git). This is the build tool we use to
+develop GraalVM languages. You also need LLVM 6, including the `opt` tool -- the
+latter is not included on macOS by default, here you can install the homebrew
+version of LLVM, which includes this tool. Note that you can use any JDK, and do
+not necessarily need GraalVM for development. In that case you'll only be able
+to run without the just-in-time compiler, but that can be fine for making and
+testing changes that are not performance sensitive.
+
+Once you have `mx` on your `PATH`, you can run `mx build` in this
+repository. This will initially download the required dependencies next to the
+repository and build Python. If it succeeds without errors, you should already
+be able to run `mx python` and get a REPL.
+
+If you just want to copy and paste some commands, these should get you started:
+
+    $ git clone https://github.com/graalvm/mx.git
+    $ git clone https://github.com/graalvm/graalpython.git
+    $ cd graalpython
+    $ ../mx/mx build
+    $ ../mx/mx python -c "print(42)"
+
+For development, we recommend running `mx ideinit` next. This will generate
+configurations for Eclipse, IntelliJ, and Netbeans so that you can open the
+projects in these IDEs. If you use another editor with support for the [Eclipse
+language server](https://github.com/eclipse/eclipse.jdt.ls) we also had reports
+of useable development setups with that, but it's not something we support.
+
+##### Development layout
+
+Besides the source code of the Python interpreter, we have some useful `mx`
+functions defined under the `mx.graalpython` directory. As you make changes, you
+can test always test them with `mx build && mx python`. Additionally, there are
+various "gates" that we use on our CI systems to check any code that goes
+in. You can run all of these using `mx python-gate` or just some by using `mx
+python-gate --tags [TAG]`. Two interesting gates to run that cover most things
+are:
+
+- `python-unittest` - Run the unittests written in Python, including those for the C extension API
+- `python-license` - Check that all files have the correct copyright headers applied to them
+
+###### Builtin modules and classes
+
+For the most part, builtin modules and classes are implemented in the
+`com.oracle.graal.python.builtins` package. For each module or class, there's
+Java class annoted with `@CoreFunctions`. Each function in a module or a class
+is implemented in a Node annotated with `@Builtin`. Take a look at the existing
+implementations to get a feel for how this is done. For now, when adding new
+classes or modules, they need to be added to the list in
+`com.oracle.graal.python.builtins.Python3Core`.
+
+Some builtin functions, modules, and classes are implemented in pure Python. The
+files for this are in `graalpython/lib-graalpython`. These files are listed in
+the Java `com.oracle.graal.python.builtins.Python3Core` class. Take a look at
+these files to see what they do. If a file is called exactly as a built-in
+module is, it is executed in the context of that module during startup, so some
+of our modules are implemented both in Java and Python. If the name matches no
+existing module, the file is executed just for the side-effects.
+
+###### Python C API
+
+The C implementation and headers for our C API are in
+`graalpython/com.oracle.graal.python.cext`. The naming is analogous to C
+Python's source names. This folder also includes a `modules` folder for built-in
+modules that we have adapted from C Python.

doc/CONTRIBUTING.md

@@ -79,12 +79,12 @@ print(al) # prints [1, 12]
 In addition to the `type` builtin method, the `java` module, exposes the following 
 methods as well:
 
-Builtin | Specification
---- | ---
+Builtin                  | Specification
+---                      | ---
 `instanceof(obj, class)` | returns `True` if `obj` is an instance of `class` (`class` must be a foreign object class)
-`is_function(obj)` | returns `True` if `obj` is a Java host language function wrapped using Truffle interop
-`is_object(obj)` | returns `True` if `obj` if the argument is Java host language object wrapped using Truffle interop
-`is_symbol(obj)` | returns `True` if `obj` if the argument is a Java host symbol, representing the constructor and static members of a Java class, as obtained by `java.type`
+`is_function(obj)`       | returns `True` if `obj` is a Java host language function wrapped using Truffle interop
+`is_object(obj)`         | returns `True` if `obj` if the argument is Java host language object wrapped using Truffle interop
+`is_symbol(obj)`         | returns `True` if `obj` if the argument is a Java host symbol, representing the constructor and static members of a Java class, as obtained by `java.type`
 
 ```python
 import java