forked from Rust-related/RustPython
Update READMEs
This commit is contained in:
coolreader18
2
LICENSE
2
LICENSE
@@ -1,6 +1,6 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2018 Shing Lyu
|
||||
Copyright (c) 2019 RustPython Team
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
||||
@@ -1,10 +1,13 @@
|
||||
Standard Library for RustPython
|
||||
===============================
|
||||
# Standard Library for RustPython
|
||||
|
||||
This directory contains all of the Python files that make up the standard library for RustPython.
|
||||
This directory contains all of the Python files that make up the standard
|
||||
library for RustPython.
|
||||
|
||||
Most of these files are copied over from the CPython repository(the 3.7 branch), with slight modifications to allow them
|
||||
to work under RustPython. The current goal is to complete the standard library with as few modifications as possible.
|
||||
Current modifications are just temporary workarounds for bugs/missing feature within the RustPython implementation.
|
||||
Most of these files are copied over from the CPython repository (the 3.7
|
||||
branch), with slight modifications to allow them to work under RustPython. The
|
||||
current goal is to complete the standard library with as few modifications as
|
||||
possible. Current modifications are just temporary workarounds for bugs/missing
|
||||
feature within the RustPython implementation.
|
||||
|
||||
The first target is to run the ``unittest`` module, so we can leverage the CPython test suite.
|
||||
The first big module we are targeting is `unittest`, so we can leverage the
|
||||
CPython test suite.
|
||||
|
||||
92
README.md
92
README.md
@@ -2,7 +2,8 @@
|
||||
|
||||
# RustPython
|
||||
|
||||
A Python-3 (CPython >= 3.5.0) Interpreter written in Rust :snake: :scream: :metal:.
|
||||
A Python-3 (CPython >= 3.5.0) Interpreter written in Rust :snake: :scream:
|
||||
:metal:.
|
||||
|
||||
[](https://travis-ci.org/RustPython/RustPython)
|
||||
[](https://dev.azure.com/ryan0463/ryan/_build/latest?definitionId=1&branchName=master)
|
||||
@@ -11,9 +12,9 @@ A Python-3 (CPython >= 3.5.0) Interpreter written in Rust :snake: :scream: :meta
|
||||
[](https://github.com/RustPython/RustPython/graphs/contributors)
|
||||
[](https://gitter.im/rustpython/Lobby)
|
||||
|
||||
# Usage
|
||||
## Usage
|
||||
|
||||
### Check out our [online demo](https://rustpython.github.io/demo/) running on WebAssembly.
|
||||
#### Check out our [online demo](https://rustpython.github.io/demo/) running on WebAssembly.
|
||||
|
||||
To test RustPython, do the following:
|
||||
|
||||
@@ -29,38 +30,44 @@ Or use the interactive shell:
|
||||
>>>>> 2+2
|
||||
4
|
||||
|
||||
# Disclaimer
|
||||
## Disclaimer
|
||||
|
||||
RustPython is in a development phase and should not be used in production or a fault intolerant setting.
|
||||
RustPython is in a development phase and should not be used in production or a
|
||||
fault intolerant setting.
|
||||
|
||||
Our current build supports only a subset of Python syntax.
|
||||
Our current build supports only a subset of Python syntax.
|
||||
|
||||
Contribution is also more than welcome! See our contribution section for more information on this.
|
||||
Contribution is also more than welcome! See our contribution section for more
|
||||
information on this.
|
||||
|
||||
# Conference videos
|
||||
## Conference videos
|
||||
|
||||
Checkout those talks on conferences:
|
||||
|
||||
- [FOSDEM 2019](https://www.youtube.com/watch?v=nJDY9ASuiLc)
|
||||
- [EuroPython 2018](https://www.youtube.com/watch?v=YMmio0JHy_Y)
|
||||
|
||||
# Use cases
|
||||
## Use cases
|
||||
|
||||
Allthough rustpython is a very young project, it is already used in the wild:
|
||||
|
||||
- [pyckitup](https://github.com/pickitup247/pyckitup): a game engine written in rust.
|
||||
- [codingworkshops.org](https://github.com/chicode/codingworkshops): a site where you can learn how to code.
|
||||
- [pyckitup](https://github.com/pickitup247/pyckitup): a game engine written in
|
||||
rust.
|
||||
- [codingworkshops.org](https://github.com/chicode/codingworkshops): a site
|
||||
where you can learn how to code.
|
||||
|
||||
# Goals
|
||||
## Goals
|
||||
|
||||
- Full Python-3 environment entirely in Rust (not CPython bindings)
|
||||
- A clean implementation without compatibility hacks
|
||||
|
||||
# Documentation
|
||||
## Documentation
|
||||
|
||||
Currently along with other areas of the project, documentation is still in an early phase.
|
||||
Currently along with other areas of the project, documentation is still in an
|
||||
early phase.
|
||||
|
||||
You can read the [online documentation](https://rustpython.github.io/website/rustpython/index.html) for the latest code on master.
|
||||
You can read the [online documentation](https://docs.rs/rustpython-vm) for the
|
||||
latest release.
|
||||
|
||||
You can also generate documentation locally by running:
|
||||
|
||||
@@ -71,29 +78,28 @@ $ cargo doc --no-deps --all # Excluding all dependencies
|
||||
|
||||
Documentation HTML files can then be found in the `target/doc` directory.
|
||||
|
||||
If you wish to update the online documentation, push directly to the `release` branch (or ask a maintainer to do so). This will trigger a Travis build that updates the documentation and WebAssembly demo page.
|
||||
## Contributing
|
||||
|
||||
# Contributing
|
||||
Contributions are more than welcome, and in many cases we are happy to guide
|
||||
contributors through PRs or on gitter.
|
||||
|
||||
Contributions are more than welcome, and in many cases we are happy to guide contributors through PRs or on gitter.
|
||||
With that in mind, please note this project is maintained by volunteers, some of
|
||||
the best ways to get started are below:
|
||||
|
||||
With that in mind, please note this project is maintained by volunteers, some of the best ways to get started are below:
|
||||
Most tasks are listed in the
|
||||
[issue tracker](https://github.com/RustPython/RustPython/issues). Check issues
|
||||
labeled with `good first issue` if you wish to start coding.
|
||||
|
||||
Most tasks are listed in the [issue tracker](https://github.com/RustPython/RustPython/issues).
|
||||
Check issues labeled with `good first issue` if you wish to start coding.
|
||||
Another approach is to checkout the source code: builtin functions and object
|
||||
methods are often the simplest and easiest way to contribute.
|
||||
|
||||
Another approach is to checkout the source code: builtin functions and object methods are often the simplest
|
||||
and easiest way to contribute.
|
||||
You can also simply run `./whats_left.sh` to assist in finding any unimplemented
|
||||
method.
|
||||
|
||||
You can also simply run
|
||||
`./whats_left.sh` to assist in finding any
|
||||
unimplemented method.
|
||||
## Using a standard library
|
||||
|
||||
# Using a standard library
|
||||
|
||||
As of now the standard library is under construction. You can
|
||||
use a standard library by setting the RUSTPYTHONPATH environment
|
||||
variable.
|
||||
As of now the standard library is under construction. You can use a standard
|
||||
library by setting the RUSTPYTHONPATH environment variable.
|
||||
|
||||
To do this, follow this method:
|
||||
|
||||
@@ -102,32 +108,38 @@ $ export RUSTPYTHONPATH=~/GIT/RustPython/Lib
|
||||
$ cargo run -- -c 'import xdrlib'
|
||||
```
|
||||
|
||||
You can play around
|
||||
with other standard libraries for python. For example,
|
||||
the [ouroboros library](https://github.com/pybee/ouroboros).
|
||||
You can play around with other standard libraries for python. For example, the
|
||||
[ouroboros library](https://github.com/pybee/ouroboros).
|
||||
|
||||
# Compiling to WebAssembly
|
||||
## Compiling to WebAssembly
|
||||
|
||||
[See this doc](wasm/README.md)
|
||||
|
||||
# Community
|
||||
## Community
|
||||
|
||||
Chat with us on [gitter][gitter].
|
||||
|
||||
# Code of conduct
|
||||
## Code of conduct
|
||||
|
||||
Our code of conduct [can be found here](code-of-conduct.md).
|
||||
|
||||
# Credit
|
||||
## Credit
|
||||
|
||||
The initial work was based on [windelbouwman/rspython](https://github.com/windelbouwman/rspython) and [shinglyu/RustPython](https://github.com/shinglyu/RustPython)
|
||||
The initial work was based on
|
||||
[windelbouwman/rspython](https://github.com/windelbouwman/rspython) and
|
||||
[shinglyu/RustPython](https://github.com/shinglyu/RustPython)
|
||||
|
||||
[gitter]: https://gitter.im/rustpython/Lobby
|
||||
|
||||
# Links
|
||||
## Links
|
||||
|
||||
These are some useful links to related projects:
|
||||
|
||||
- https://github.com/ProgVal/pythonvm-rust
|
||||
- https://github.com/shinglyu/RustPython
|
||||
- https://github.com/windelbouwman/rspython
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT license. Please see the
|
||||
[LICENSE](LICENSE) file for more details.
|
||||
|
||||
@@ -1,9 +1,8 @@
|
||||
|
||||
# Benchmarking
|
||||
|
||||
These are some files to determine performance of rustpython.
|
||||
|
||||
# Usage
|
||||
## Usage
|
||||
|
||||
Install pytest and pytest-benchmark:
|
||||
|
||||
@@ -13,7 +12,11 @@ Then run:
|
||||
|
||||
$ pytest
|
||||
|
||||
# Benchmark source
|
||||
You can also benchmark the Rust benchmarks by just running
|
||||
`cargo +nightly bench` from the root of the repository. Make sure you have Rust
|
||||
nightly installed, as the benchmarking parts of the standard library are still
|
||||
unstable.
|
||||
|
||||
## Benchmark source
|
||||
|
||||
- https://benchmarksgame-team.pages.debian.net/benchmarksgame/program/nbody-python3-2.html
|
||||
|
||||
|
||||
@@ -5,8 +5,9 @@ extern crate rustpython_parser;
|
||||
extern crate rustpython_vm;
|
||||
extern crate test;
|
||||
|
||||
use rustpython_compiler::compile;
|
||||
use rustpython_vm::pyobject::PyResult;
|
||||
use rustpython_vm::{compile, VirtualMachine};
|
||||
use rustpython_vm::VirtualMachine;
|
||||
|
||||
#[bench]
|
||||
fn bench_tokenization(b: &mut test::Bencher) {
|
||||
@@ -91,7 +92,7 @@ fn bench_rustpy_nbody(b: &mut test::Bencher) {
|
||||
// NOTE: Take long time.
|
||||
let source = include_str!("./benchmarks/nbody.py");
|
||||
|
||||
let vm = VirtualMachine::new();
|
||||
let vm = VirtualMachine::default();
|
||||
|
||||
let code = match vm.compile(source, &compile::Mode::Single, "<stdin>".to_string()) {
|
||||
Ok(code) => code,
|
||||
@@ -110,7 +111,7 @@ fn bench_rustpy_mandelbrot(b: &mut test::Bencher) {
|
||||
// NOTE: Take long time.
|
||||
let source = include_str!("./benchmarks/mandelbrot.py");
|
||||
|
||||
let vm = VirtualMachine::new();
|
||||
let vm = VirtualMachine::default();
|
||||
|
||||
let code = match vm.compile(source, &compile::Mode::Single, "<stdin>".to_string()) {
|
||||
Ok(code) => code,
|
||||
|
||||
@@ -5,8 +5,6 @@ import sys
|
||||
import pytest
|
||||
import subprocess
|
||||
|
||||
from benchmarks import nbody
|
||||
|
||||
# Interpreters:
|
||||
rustpython_exe = '../target/release/rustpython'
|
||||
cpython_exe = sys.executable
|
||||
|
||||
@@ -1,20 +1,18 @@
|
||||
# Test snippets
|
||||
|
||||
This directory contains two sets of test snippets which can be run in
|
||||
Python. The `snippets/` directory contains functional tests, and the
|
||||
`benchmarks/` directory contains snippets for use in benchmarking
|
||||
RustPython's performance.
|
||||
This directory contains two sets of test snippets which can be run in Python.
|
||||
The `snippets/` directory contains functional tests, and the `benchmarks/`
|
||||
directory contains snippets for use in benchmarking RustPython's performance.
|
||||
|
||||
## Generates the test for not implemented methods
|
||||
## Setup
|
||||
|
||||
run using cpython not_impl_gen.py it automatically generate a
|
||||
test snippet to check not yet implemented methods
|
||||
Our testing depends on [pytest](https://pytest.org), which you can either
|
||||
install globally using pip or locally using our
|
||||
[pipenv](https://docs.pipenv.org).
|
||||
|
||||
## Running with CPython + RustPython
|
||||
## Running
|
||||
|
||||
One way to run these snippets is by using CPython to do the parsing and
|
||||
compilation to bytecode. When this is done, run the bytecode with rustpython.
|
||||
|
||||
## Running with RustPython
|
||||
|
||||
The other option is to run all snippets with RustPython.
|
||||
Simply run `pytest` in this directory, and the tests should run (and hopefully
|
||||
pass). If it hangs for a long time, that's because it's building RustPython in
|
||||
release mode, which should take less time than it would to run every test
|
||||
snippet with RustPython compiled in debug mode.
|
||||
|
||||
@@ -1,11 +1,15 @@
|
||||
|
||||
# Compiling to webassembly
|
||||
|
||||
At this stage RustPython only has preliminary support for web assembly. The instructions here are intended for developers or those wishing to run a toy example.
|
||||
At this stage RustPython only has preliminary support for web assembly. The
|
||||
instructions here are intended for developers or those wishing to run a toy
|
||||
example.
|
||||
|
||||
## Setup
|
||||
|
||||
To get started, install [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/) and `npm`. ([wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/whirlwind-tour/basic-usage.html) should be installed by `wasm-pack`. if not, install it yourself)
|
||||
To get started, install
|
||||
[wasm-pack](https://rustwasm.github.io/wasm-pack/installer/) and `npm`.
|
||||
([wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/whirlwind-tour/basic-usage.html)
|
||||
should be installed by `wasm-pack`. if not, install it yourself)
|
||||
|
||||
<!-- Using `rustup` add the compile target `wasm32-unknown-emscripten`. To do so you will need to have [rustup](https://rustup.rs/) installed.
|
||||
|
||||
@@ -25,26 +29,26 @@ cd emsdk-portable/
|
||||
|
||||
## Build
|
||||
|
||||
Move into the `wasm` directory. This directory contains a library crate for interop
|
||||
with python to rust to js and back in `wasm/lib`, the demo website found at
|
||||
https://rustpython.github.io/demo in `wasm/demo`, and an example of how to use
|
||||
the crate as a library in one's own JS app in `wasm/example`.
|
||||
Move into the `wasm` directory. This directory contains a library crate for
|
||||
interop with python to rust to js and back in `wasm/lib`, the demo website found
|
||||
at https://rustpython.github.io/demo in `wasm/demo`, and an example of how to
|
||||
use the crate as a library in one's own JS app in `wasm/example`.
|
||||
|
||||
```sh
|
||||
cd wasm
|
||||
```
|
||||
|
||||
Go to the demo directory. This is the best way of seeing the changes made to either
|
||||
the library or the JS demo, as the `rustpython_wasm` module is set to the global
|
||||
JS variable `rp` on the website.
|
||||
Go to the demo directory. This is the best way of seeing the changes made to
|
||||
either the library or the JS demo, as the `rustpython_wasm` module is set to the
|
||||
global JS variable `rp` on the website.
|
||||
|
||||
```sh
|
||||
cd demo
|
||||
```
|
||||
|
||||
Now, start the webpack development server. It'll compile the crate and then
|
||||
the demo app. This will likely take a long time, both the wasm-pack portion and
|
||||
the webpack portion (from after it says "Your crate has been correctly compiled"),
|
||||
Now, start the webpack development server. It'll compile the crate and then the
|
||||
demo app. This will likely take a long time, both the wasm-pack portion and the
|
||||
webpack portion (from after it says "Your crate has been correctly compiled"),
|
||||
so be patient.
|
||||
|
||||
```sh
|
||||
@@ -56,17 +60,24 @@ the text box or browser devtools with:
|
||||
|
||||
```js
|
||||
rp.pyEval(
|
||||
`
|
||||
`
|
||||
print(js_vars['a'] * 9)
|
||||
`,
|
||||
{
|
||||
vars: {
|
||||
a: 9
|
||||
{
|
||||
vars: {
|
||||
a: 9
|
||||
}
|
||||
}
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
Alternatively, you can run `npm run build` to build the app once, without watching
|
||||
for changes, or `npm run dist` to build the app in release mode, both for the
|
||||
crate and webpack.
|
||||
Alternatively, you can run `npm run build` to build the app once, without
|
||||
watching for changes, or `npm run dist` to build the app in release mode, both
|
||||
for the crate and webpack.
|
||||
|
||||
## Updating the demo
|
||||
|
||||
If you wish to update the WebAssembly demo,
|
||||
[open a pull request](https://github.com/RustPython/RustPython/compare/release...master)
|
||||
to merge `master` into the `release` branch. This will trigger a Travis build
|
||||
that updates the demo page.
|
||||
|
||||
@@ -13,7 +13,7 @@ A Python-3 (CPython >= 3.5.0) Interpreter written in Rust.
|
||||
|
||||
## Usage
|
||||
|
||||
### Check out our [online demo](https://rustpython.github.io/demo/) running on WebAssembly.
|
||||
#### Check out our [online demo](https://rustpython.github.io/demo/) running on WebAssembly.
|
||||
|
||||
## Goals
|
||||
|
||||
|
||||
Reference in New Issue
Block a user