From 5821bac2dcd5247d981718801b05ea27172d4d6e Mon Sep 17 00:00:00 2001 From: coolreader18 <33094578+coolreader18@users.noreply.github.com> Date: Tue, 16 Jul 2019 19:13:07 -0500 Subject: [PATCH] Update READMEs --- LICENSE | 2 +- Lib/README.md | 17 ++++--- README.md | 92 ++++++++++++++++++++--------------- benchmarks/README.md | 11 +++-- benchmarks/bench.rs | 7 +-- benchmarks/test_benchmarks.py | 2 - tests/README.md | 26 +++++----- wasm/README.md | 53 ++++++++++++-------- wasm/lib/README.md | 2 +- 9 files changed, 119 insertions(+), 93 deletions(-) diff --git a/LICENSE b/LICENSE index d3a3b7bbb4..bd178e7ad9 100644 --- a/LICENSE +++ b/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 diff --git a/Lib/README.md b/Lib/README.md index b3aade7bfa..535d8939e8 100644 --- a/Lib/README.md +++ b/Lib/README.md @@ -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. diff --git a/README.md b/README.md index 46a460e4ea..70b8f24dc1 100644 --- a/README.md +++ b/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:. [![Build Status](https://travis-ci.org/RustPython/RustPython.svg?branch=master)](https://travis-ci.org/RustPython/RustPython) [![Build Status](https://dev.azure.com/ryan0463/ryan/_apis/build/status/RustPython.RustPython?branchName=master)](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 [![Contributors](https://img.shields.io/github/contributors/RustPython/RustPython.svg)](https://github.com/RustPython/RustPython/graphs/contributors) [![Gitter](https://badges.gitter.im/RustPython/Lobby.svg)](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. diff --git a/benchmarks/README.md b/benchmarks/README.md index 464dc65f21..dfb6bcb0b1 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -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 - diff --git a/benchmarks/bench.rs b/benchmarks/bench.rs index 55f2763a5e..5a67ac3928 100644 --- a/benchmarks/bench.rs +++ b/benchmarks/bench.rs @@ -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, "".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, "".to_string()) { Ok(code) => code, diff --git a/benchmarks/test_benchmarks.py b/benchmarks/test_benchmarks.py index 571785e60f..49c9a1adaf 100644 --- a/benchmarks/test_benchmarks.py +++ b/benchmarks/test_benchmarks.py @@ -5,8 +5,6 @@ import sys import pytest import subprocess -from benchmarks import nbody - # Interpreters: rustpython_exe = '../target/release/rustpython' cpython_exe = sys.executable diff --git a/tests/README.md b/tests/README.md index ba24ab8bc2..b748fd0047 100644 --- a/tests/README.md +++ b/tests/README.md @@ -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. diff --git a/wasm/README.md b/wasm/README.md index 2dd390b706..16c0400e70 100644 --- a/wasm/README.md +++ b/wasm/README.md @@ -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)