Skip to content

Commit 59d1486

Browse files
timfeltimfel
committed
Update github readme
1 parent c211c49 commit 59d1486

File tree

8 files changed

+177
-57
lines changed

8 files changed

+177
-57
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ language runtime. The main focus is on user-observable behavior of the engine.
2727
** creating new script with local maven repo for testing: `jbang init --template=graalpy_local_repo@oracle/graalpython -Dpath_to_local_repo=/absolute/path/to/local/maven/repository myscript.java'
2828

2929
## Version 23.1.0
30-
* Oracle GraalPy distributions (previously known as GraalPy Enterprise) are now available under the [GFTC license](https://www.oracle.com/downloads/licenses/graal-free-license.html). The community builds published on Github have been renamed to `graalpy-community-<version>-<os>-<arch>.tar.gz`.
30+
* GraalPy distributions (previously known as GraalPy Enterprise) are now available under the [GFTC license](https://www.oracle.com/downloads/licenses/graal-free-license.html). The community builds published on Github have been renamed to `graalpy-community-<version>-<os>-<arch>.tar.gz`.
3131
* Add support for the sqlite3 module. This allows many packages like `coverage` or `Flask-SQLAlchemy` to work on top of this embedded database.
3232
* Provide Windows distributions of GraalPy. This is the first preview of Windows support for GraalPy, and there are limitations, but pure Python packages like Pygal can be installed with `python -m pip --no-cache install pygal`.
3333
* The GraalPy standalone tool was updated. You can now build single-file executable Python binaries for Linux, Windows, and macOS. The tool can also generate a skeleton Maven project that sets up a polyglot embedding of Python packages into Java.

‎README.md

Lines changed: 155 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,181 @@
11
# GraalPy, the GraalVM Implementation of Python
22

3-
GraalPy is an implementation of the Python language on top of GraalVM.
4-
A primary goal is to support PyTorch, SciPy, and their constituent libraries, as well as to work with other data science and machine learning libraries from the rich Python ecosystem.
5-
GraalPy can usually execute pure Python code faster than CPython, and nearly match CPython performance when C extensions are involved.
6-
GraalPy currently aims to be compatible with Python 3.10.
7-
While many workloads run fine, any Python program that uses external packages could hit something unsupported.
8-
At this point, the Python implementation is made available for experimentation and curious end-users.
9-
We welcome issue reports of all kinds and are working hard to close our compatibility gaps.
3+
GraalPy is a high-performance implementation of the [Python](https://www.python.org/) language for the JVM built on [GraalVM](https://www.graalvm.org/) technology.
104

11-
## Installation
5+
## Getting Started
126

13-
The easiest option to try GraalPy is [pyenv](https://github.com/pyenv/pyenv/), the Python version manager.
14-
It allows you to easily install different GraalPy releases.
15-
To install version 23.1.0, for example, just run `pyenv install graalpy-community-23.1.0`.
7+
<details>
8+
<summary><strong>Embedding GraalPy in Java</strong></summary>
169

17-
Another option is to use [Conda-Forge](https://conda-forge.org/).
18-
To get an environment with the latest version of GraalPy, use the following command:
10+
GraalPy is [available on Maven Central](https://central.sonatype.com/artifact/org.graalvm.polyglot/python) for inclusion in Java projects:
1911

20-
```bash
21-
conda create -c conda-forge -n graalpy graalpy
12+
```
13+
<dependency>
14+
<groupId>org.graalvm.polyglot</groupId>
15+
<artifactId>python</artifactId>
16+
<version>23.1.2</version>
17+
<type>pom</type>
18+
</dependency>
2219
```
2320

24-
To try GraalPy with a full GraalVM, including the support for Java embedding and interoperability with other languages, you can use the bundled releases from [www.graalvm.org](https://www.graalvm.org/downloads/).
21+
</details>
2522

26-
>**Note:** There is currently no installer for Windows.
23+
<details>
24+
<summary><strong>Replacing CPython with GraalPy</strong></summary>
2725

28-
## Building from Source
26+
* Linux
2927

30-
#### Requirements
28+
The easiest way to install GraalPy on Linux is to use [Pyenv](https://github.com/pyenv/pyenv) (the Python version manager).
29+
To install version 23.1.1 using Pyenv, run the following commands:
30+
```bash
31+
pyenv install graalpy-23.1.1
32+
```
33+
```bash
34+
pyenv shell graalpy-23.1.1
35+
```
36+
37+
Alternatively, you can download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases).
38+
39+
1. Find the download that matches the pattern _graalpy-XX.Y.Z-linux-amd64.tar.gz_ or _graalpy-XX.Y.Z-linux-aarch64.tar.gz_ (depending on your platform) and download.
40+
2. Uncompress the file and update your `PATH` environment variable to include the _graalpy-XX.Y.Z-linux-amd64/bin_ (or _graalpy-XX.Y.Z-linux-aarch64/bin_) directory.
3141

32-
* [mx](https://github.com/graalvm/mx)
42+
* macOS
3343

34-
There is a separate Python tool for GraalVM development. This tool must be downloaded and added to your PATH:
35-
36-
```shell
37-
git clone https://github.com/graalvm/mx.git
38-
export PATH=$PWD/mx:$PATH
44+
The easiest way to install GraalPy on macOS is to use [Pyenv](https://github.com/pyenv/pyenv) (the Python version manager).
45+
To install version 23.1.1 using Pyenv, run the following commands:
46+
```bash
47+
pyenv install graalpy-23.1.1
3948
```
40-
* LabsJDK
41-
42-
The following command will download and install JDKs upon which to build GraalVM. If successful, it will print the path for the value of your `JAVA_HOME` environment variable.
43-
```shell
44-
mx fetch-jdk
49+
```bash
50+
pyenv shell graalpy-23.1.1
4551
```
46-
47-
#### Building
52+
Alternatively, you can download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases).
53+
54+
1. Find the download that matches the pattern _graalpy-XX.Y.Z-macos-amd64.tar.gz_ or _graalpy-XX.Y.Z-macos-aarch64.tar.gz_ (depending on your platform) and download.
55+
2. Remove the quarantine attribute.
56+
```bash
57+
sudo xattr -r -d com.apple.quarantine /path/to/graalpy
58+
```
59+
For example:
60+
```bash
61+
sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-23.1.1
62+
```
63+
3. Uncompress the file and update your `PATH` environment variable to include to the _graalpy-XX.Y.Z-macos-amd64/bin_ (or _graalpy-XX.Y.Z-macos-aarch64/bin_) directory.
64+
65+
* Windows
66+
67+
The Windows support of GraalPy is still experimental, so not all features and packages may be available.
68+
69+
1. Find and download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases) that matches the pattern _graalpy-XX.Y.Z-windows-amd64.tar.gz_.
70+
2. Uncompress the file and update your `PATH` variable to include to the _graalpy-XX.Y.Z-windows-amd64/bin_ directory.
71+
72+
</details>
73+
<details>
74+
<summary><strong>Using GraalPy in Github Actions</strong></summary>
75+
76+
The _setup-python_ action supports GraalPy:
77+
78+
```
79+
- name: Setup GraalPy
80+
uses: actions/setup-python@main
81+
with:
82+
python-version: graalpy # or graalpy23.1 to pin a version
83+
```
84+
85+
</details>
86+
<details>
87+
<summary><strong>Migrating Jython Scripts to GraalPy</strong></summary>
88+
89+
To run Jython scripts, you will need a GraalPy distribution running on the JVM so you can access Java classes from Python scripts.
90+
91+
* Linux
92+
93+
1. Find and download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases) that matches the pattern _graalpy-jvm-XX.Y.Z-linux-amd64.tar.gz_ or _graalpy-jvm-XX.Y.Z-linux-aarch64.tar.gz_ (depending on your platform) and download.
94+
2. Uncompress the file and update your `PATH` environment variable to include the _graalpy-jvm-XX.Y.Z-linux-amd64/bin_ (or _graalpy-jvm-XX.Y.Z-linux-aarch64/bin_) directory.
95+
3. Run your scripts with `graalpy --python.EmulateJython`.
4896
49-
Run `mx --dy /compiler python-gvm` in the root directory of the `graalpython` repository.
50-
If the build succeeds, it will print the full path to the `graalpy` executable as the last line of output.
51-
This builds a `bash` launcher that executes GraalPy on the JVM.
52-
To build a native launcher for lower footprint and better startup, run `mx python-svm` instead.
97+
* macOS
5398
54-
For more information and some examples of what you can do with GraalPy, see the [reference documentation](https://www.graalvm.org/reference-manual/python/).
99+
1. Find and download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases) that matches the pattern _graalpy-jvm-XX.Y.Z-macos-amd64.tar.gz_ or _graalpy-jvm-XX.Y.Z-macos-aarch64.tar.gz_ (depending on your platform) and download.
100+
2. Remove the quarantine attribute.
101+
```bash
102+
sudo xattr -r -d com.apple.quarantine /path/to/graalpy
103+
```
104+
For example:
105+
```bash
106+
sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-23.1.1
107+
```
108+
3. Uncompress the file and update your `PATH` environment variable to include to the _graalpy-jvm-XX.Y.Z-macos-amd64/bin_ (or _graalpy-jvm-XX.Y.Z-macos-aarch64/bin_) directory.
109+
4. Run your scripts with `graalpy --python.EmulateJython`.
55110
56-
## Polyglot Usage
111+
* Windows
57112
58-
See the [documentation](docs/user/Interoperability.md) that describes how we implement
59-
cross-language interoperability.
60-
This should give you an idea about how to use it.
113+
1. Find and download a compressed GraalPy installation file from [GitHub releases](https://github.com/oracle/graalpython/releases) that matches the pattern _graalpy-jvm-XX.Y.Z-windows-amd64.tar.gz_.
114+
2. Uncompress the file and update your `PATH` variable to include to the _graalpy-jvm-XX.Y.Z-windows-amd64/bin_ directory.
115+
3. Run your scripts with `graalpy --python.EmulateJython`.
61116
62-
## Jython Support
117+
</details>
63118
64-
We are working on a mode that is "mostly compatible" with some of Jython's
65-
features, minus of course that Jython implements Python 2.7 and we implement
66-
Python 3.10+.
119+
## Current Status
120+
121+
![](docs/mcd.svg)
122+
![](docs/performance.svg)
123+
124+
## Aims and Benefits of GraalPy
125+
126+
* **Convenient, low-overhead integration with Java and other languages.**
127+
128+
Java, JavaScript, Ruby, and other languages that run on the JVM can be used [conveniently with GraalPy](docs/user/Interoperability.md).
129+
GraalPy also integrates with JVM tools such as VisualVM or JFR, and comes with [profilers, memory samplers, and debuggers](docs/user/Tooling.md) provided as part of GraalVM's Truffle framework.
130+
131+
* **Compatible with the Python ecosystem**
132+
133+
We run the CPython test suite on every commit and are passing ~75% of it.
134+
We also run the tests of the [top 600 PyPI packages](https://hugovk.github.io/top-pypi-packages/) on GraalPy every day.
135+
For more than 96% of the top 600 packages, there is at least one recent version that installs successfully and we are currently passing over 50% of all test cases in those top 600 packages.
136+
137+
* **Run Python code faster**
138+
139+
GraalPy can usually execute pure Python code faster than CPython.
140+
We see a geomean speedup of 4 on the [Python Performance Benchmark Suite](https://pyperformance.readthedocs.io/) over CPython.
141+
142+
* **Support C extensions**
143+
144+
GraalPy supports most of the public [CPython C API](https://docs.python.org/3/c-api/index.html) as well as the [HPy API](https://hpyproject.org/).
145+
It supports many native libraries including PyTorch, Tensorflow, SciPy, as well many other data science and machine learning libraries from the rich Python ecosystem.
146+
Performance when C extensions are involved is close to CPython, but can vary a lot depending on the specific interactions of C extension code and Python code.
147+
148+
## Python on the JVM
149+
150+
GraalPy is a first-class citizen of the JVM ecosystem that you can easily embed in your Java applications.
151+
You can use GraalPy with GraalVM JDK, Oracle JDK, or OpenJDK.
152+
You can easily add GraalPy to your Java application using [Maven build tools](docs/user/PythonStandaloneBinaries.md#embedding-graalpy-in-a-java-application).
153+
Python objects support the same [interoperability protocol](docs/user/Interoperability.md) as other GraalVM languages and behave naturally in Java.
154+
There are also [many options](docs/user/PythonNativeimages.md) to tweak GraalPy for GraalVM Native Images to reduce footprint.
155+
When embedded into Java, GraalPy also emulates many of the Python [OS interfaces](docs/user/OsInterface.md#java-backend) with standard Java APIs, so embedders have full control over standard streams, file system, or socket access.
156+
157+
## Migration from CPython
158+
159+
GraalPy should in many cases work as a drop-in replacement for CPython.
160+
You can use `pip` to install packages as usual.
161+
However, packages with C code usually do not provide binaries for GraalPy, so they will be automatically compiled during installation.
162+
This means that build tools have to be available and installation may take longer.
163+
We provide [Github actions](scripts/wheelbuilder) to help you build binary packages with the correct dependencies.
164+
165+
## Migration from Jython
166+
167+
Most existing Jython code that uses Java integration will be based on a stable Jython release&mdash;however, these are only available in Python 2.x versions.
168+
First, to migrate your code from Python 2 to Python 3, follow [the official guide from the Python community](https://docs.python.org/3/howto/pyporting.html).
169+
To facilitate migration from Jython, GraalPy provides a mode that is "mostly compatible" with some of Jython's features, minus of course that Jython implements Python 2.7 and we implement Python 3+.
67170
We describe the current status of the compatibility mode [here](docs/user/Jython.md).
68171
69-
We are working on a mode that is "mostly compatible" with some of Jython's features, considering the fact that Jython implements Python 2.7 and we implement Python 3.10+.
70-
For more details about compatibility, see [here](docs/user/Jython.md).
172+
## Documentation
173+
174+
More user documentation is available in [docs/user](docs/user).
175+
176+
## Contact
177+
178+
The best way to get in touch with us is to join the `#graalpy` channel on [GraalVM Slack](https://www.graalvm.org/slack-invitation/).
71179
72180
## Contributing
73181

‎docs/contributor/CONTRIBUTING.md

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,12 @@ Please also take some time to review our [code of conduct](http://www.graalvm.or
1111

1212
The first thing you want to do is to set up [`mx`](https://github.com/graalvm/mx.git).
1313
This is the build tool we use to develop GraalVM languages.
14-
Note that you can use any JDK, and do not need GraalVM for development.
15-
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.
14+
```shell
15+
git clone https://github.com/graalvm/mx.git
16+
```
17+
Make sure to add the `mx` directory to your `PATH`.
18+
19+
You can always use the latest stable JDK for development.
1620
You can also download a suitable JDK using mx:
1721
```bash
1822
mx fetch-jdk
@@ -24,7 +28,7 @@ For building GraalPy, you will also need some native build tools and libraries.
2428
sudo apt install build-essential libc++-12-dev zlib1g-dev cmake
2529
```
2630

27-
Lastly, download maven, extract it and include it on your `PATH`.
31+
Lastly, download maven, extract it and include it on your `PATH`.
2832

2933
Once you have all the necessary tools, you can run `mx build` in this repository.
3034
This will initially download the required dependencies next to the repository and build Python.

0 commit comments

Comments
 (0)