Lines of code

What is Py2EO?
Quick Start
How to contribute
How to transpile Py to EO
Python syntax and tests coverage
Big project transpilation results
Architecture and design
How do we project Python to EOLang

What is Py2EO?

This is a transpiler of Python to EOLANG. It translates Python code to EOLANG programming language.

This transpiler receives python code as input data. Then received code is simplified with several AST->AST passes. After successfull simplification EOLANG output is generated.

EOLANG code can be translated to java and executed or analyzed statically via Polystat analyzer.

Traspiler is a source-to-source translator, source-to-source compiler (S2S compiler), transcompiler, or transpiler is a type of translator that takes the source code of a program written in a programming language as its input and produces an equivalent source code in the same or a different programming language

Quick Start

Install Java 14, get Py2EO executable.

Then, start with a simple Python program in app.py file:

print("Hello world!")

Transpile it:

java -jar <path-to-py2eo-executable> app.eo

You should get app.eo containing (among a lot of system stuff):

[] > apply
    stdout (sprintf "%s\n" ((pystring "Hello world!").as-string))

For detailed instructions follow

How to contribute

Fork repository, make changes, send us a pull request. We will review your changes and apply them to the master branch shortly, provided they don't violate our quality standards. To avoid frustration, before sending us your pull request please run full Maven build:

mvn clean package

What's Next?

Test it now on your own examples following detailed instructions

Examine our ways to test it here

Explore requirements and architecture design here

Also note that you should use Maven 3.6.3 with Java 14 or Maven 3.8.4 with Java 17 (but there is no Maven 3.8 package in Ubuntu and no Java 14 package, so manual installation is needed anyway).

How to transpile Py to EO

Tested on Ubuntu (20.04+) and Windows (7+), but instructions are for Ubuntu

Install maven (sudo apt install maven) - it also installs default JDK (version 11 for now)

Install Java (JDK or JRE) version 14 (yes, exactly 14). For example you can download it here and unpack it:

cd ~

wget https://download.java.net/java/GA/jdk14.0.1/664493ef4a6946b186ff29eb326336a2/7/GPL/openjdk-14.0.1_linux-x64_bin.tar.gz

tar x -z < openjdk-14.0.1_linux-x64_bin.tar.gz

You can either use released transpiler executables or build it on your own:

Obtain Py2EO master branch sources via git clone https://github.com/polystat/py2eo.git (install git via sudo apt install git), or download zipped artifacts

Setup the PATH and JAVA_HOME variables, for example:

PATH="$PWD/jdk-14.0.1/bin/:$PATH"

export JAVA_HOME="$PWD/jdk-14.0.1/"

Check (e. g. via java -version) that version 14.* is used

Go to Py2EO root and run mvn clean package -DskipTests=true in the same command line runtime were you have set PATH and JAVA_HOME variables, if succeeded you will get transpiler/target/transpiler-${version_code}-SNAPSHOT-jar-with-dependencies.jar

Create test file with python code (e.g. sample_test.py in Py2EO root), for example with these contents:

def conditionalCheck2():
    a = 4
    b = 2

Run java -jar .\py2eo-${version_code}-SNAPSHOT-jar-with-dependencies.jar <path/to/python/file>, e. g:

java -jar .\py2eo-${version_code}-SNAPSHOT-jar-with-dependencies.jar sample_test.py

Check output .eo file in the directory with python code with the same name (e. g. sample_test.eo). Try using -o argument to specify output path and/or name if needed

Follow instructions on how to run the resulting eo code or analyze with Polystat

Additional arguments:

| Option | Action | |----------------|--------------------------------| | -h,--help | Display available options | | -o <file> | Write output to <file> | | -X,--debug | Produce execution debug output | | -v,--version | Print version information |

You can also use yegor256/py2eo image for Docker:

$ docker run -v $(pwd):/eo yegor256/py2eo hello.py -o hello.eo

This command will translate hello.py in the current directory, saving the output to the hello.eo file.

Python syntax and tests coverage

For the parser and transpiler modules there are unit tests, located in parser/src/test/scala/org/polystat/py2eo/parser/ and transpiler/src/test/scala/org/polystat/py2eo/transpiler/ respectively.

You can see this in the CI. Go to Actions → Java CI. Select any workflow run, go to test job and checkout the Build with Maven step.

We have handwritten tests that are divided into groups by type: functional (also divided into groups by constructs in accordance with the language specification), integration tests (tests for the polystat analyzer), "negative" tests, etc.

Functional tests, 1600+ lines of code. A detailed description of the particular tests is given on a separate wiki page. All these tests go through a full cycle of stages: from generating EO to executing Java. Functional tests are grouped by folders corresponding to python syntax constructs we support or are going to support, so we have easy way to calculate overall coverage and test passes successfully state. Progress is shown in each release description.

Functional tests prefixed with eo_blocked_ are known to be blocked by bugs in EO. In particular, the test eo_blocked_nfbce is blocked by https://github.com/objectionary/eo/issues/1249 , all others are blocked by https://github.com/objectionary/eo/issues/1127 .

For now we support 100.00% of the determined python syntax subset and 100.00% are passed successefully

You can see this in the enabled tests counter CI. Go to Actions → Enabled tests counter. Select any workflow run and checkout the Run counter step.

To proof this (run all test and get statistics) on clean Ubuntu (20.04+):

Install maven (sudo apt install maven) - it also installs default JDK (version 11 for now)

Install Java (JDK or JRE) version 14 (yes, exactly 14). For example, you can download it here and unpack it:

cd ~

wget https://download.java.net/java/GA/jdk14.0.1/664493ef4a6946b186ff29eb326336a2/7/GPL/openjdk-14.0.1_linux-x64_bin.tar.gz

tar x -z < openjdk-14.0.1_linux-x64_bin.tar.gz

Obtain Py2EO master branch sources via git clone https://github.com/polystat/py2eo.git (install git via sudo apt install git).

Setup the PATH and JAVA_HOME variables, for example:

PATH="$PWD/jdk-14.0.1/bin/:$PATH"

export JAVA_HOME="$PWD/jdk-14.0.1/"

Check (e. g. via `java -vers

Py2eo

Install / Use

README

Table of contents