<commit_before>= Repy Tutorial =

----
[[TOC(inline)]]
----

[[BR]]
== Introduction ==
----

This guide provides an introduction to using the repy sandbox environment.  It describes who would want to use repy, how to perform actions in the sandboxed environment, and what restrictions are placed upon the sandboxed code.   At the end of reading this document you should be able to write repy programs, manage the restrictions on programs, and understand whether repy is appropriate for a specific task or program.

It is assumed that you have a basic understanding of ports and IP addresses.  Also, a basic understanding of HTML is useful but not required.  Lastly, you need a basic understanding of the Python programming language.  If not, you might want to first read through the Python tutorial at http://www.python.org/doc/. You do not need to be a Python expert to use repy, but as repy is a subset of Python, being able to write a simple Python program is essential.

[[BR]]
== General Operations ==
----

[[BR]]
=== A Hello World example (example 1.2) ===
----

In this example, we'll wait for the user to browse a port we listen on.   When the user browses our page, we'll display a hello world webpage and then exit.   Create a file "helloworldwebpage.py" with the following text:

{{{
#!python
def hello(ip,port,sockobj, thiscommhandle,listencommhandle):<commit_msg>Revision 23 of RepyTutorial<commit_after>= Repy Tutorial =

----
[[TOC(inline)]]
----

[[BR]]
== Introduction ==
----

This guide provides an introduction to using the repy sandbox environment.  It describes who would want to use repy, how to perform actions in the sandboxed environment, and what restrictions are placed upon the sandboxed code.   At the end of reading this document you should be able to write repy programs, manage the restrictions on programs, and understand whether repy is appropriate for a specific task or program.

It is assumed that you have a basic understanding of ports and IP addresses.  Also, a basic understanding of HTML is useful but not required.  Lastly, you need a basic understanding of the Python programming language.  If not, you might want to first read through the Python tutorial at http://www.python.org/doc/. You do not need to be a Python expert to use repy, but as repy is a subset of Python, being able to write a simple Python program is essential.

[[BR]]
== General Operations with examples ==
----

[[BR]]
=== File execution (example 1.1) ===
---
Let's start with the file named 'test.py', which prints the string "Hello World" below.

{{{
#!python
print “Hello, World”
}}}

As you might know, we can run the program 'test'py' by executing the following statement on the command line:

{{{
#!python
$ python test.py
}}}

This is the normal way to execute python code. However, since this tutorial is written for those who use REPY, we need to explain two different ways to run the codes in REPY.

[[BR]]
==== Executing programs locally in REPY ====
----

You can run the program above in your computer, but you need different way to execute the program in repy.

{{{
#!python
python repy.py restrictions.test test.py
}}}

We need to make sure that you have the files named repy.py and restrictions.test in your current directory before executing the program like above.

Output is following

{{{
#!python
Hello World
Hello World
Terminated
}}}

"Hello World" was printed twice, and then the last sentence means that the program was terminated successfully. 

Not all users will see "Terminated". This only shows up on some operating systems. Other operating systems have different messages.

The test.py is called two times.

If you want to print "Hello World" only one time, you can change the code like below:

{{{
#!python
if callfunc == 'initialize':
    print "Hello World"
}}}

You need to insert if block to execute your code one time in initialize status.  

REPY is a event-driven programming language and has two events when it is executed, initialize and exit. We can have more detail about it in [PythonVsRepy All of the Python You Need to Forget to Use Repy]. 

From now on, we suppose all codes below are in the '''if callfunc == 'initialize'''' block.

[[BR]]
==== Executing programs remotely in vessels ====
----

You can also access the resources donated to you and run the program test.py in the resources you can control. You need to follow the steps below in the shell in order to  run the program in resources.

'''Step 1. Run programs in the Seattle 

To run a program, you should use the experiment manager seash.   Seash allows you to control the files running in sandboxes you control.

{{{
#!python
python seash.py
}}}

'''Step 2. Log in with my ID

Before logging in, you have to load your public and private keys. You need to make sure that you have two files containing your public and private key. The name of files is your ID and extension of files are publickey and privatekey.
For example, if your ID were john, the two files would be john.publickey and john.privatekey.

If you successfully logged in, you could notice that the prompt starts with you ID.

{{{
#!python
!> loadkeys john
!> as john
john@ !>
}}}

'''Step 3. Locate the resources(computers) you can use

{{{
#!python
john@ !> browse

Added targets: %1(10.0.1.1:1224:v9), %2(10.0.1.2:2888:v9)

Added group 'browsegood' with 2 targets

The command browse produced the output that shows resources(targets) you can control. 
}}}

In the first target %1(10.0.1.1:1224:v9), %1 is the alias of the target, 10.0.1.1 is IP address, 1224 is port number, and v9 is vessel name. The vessel is the partial portion of whole donated resources. It means that the donated resources could be one vessel or divided and assigned to more than one person. 

'''Step 4. Access the resources(vessels)

{{{
#!python
john@ !> on browsegood
}}}

'''Step 5. Run a program

We assume the program named test.py is stored in the current directory, which prints "Hello, World".

{{{
#!python
john@browsegood !> run test.py
}}}

'''Step 6. Look up the result of the program executed

{{{
#!python
john@browsegood !> show log

Log from '10.0.1.1:1224:v9':
Hello World

Log from '10.0.1.2:2888:v9':
Hello World
}}}

'''Step 7. Look up the information about the vessel you control

{{{
#!python
john@browsegood !> list

ID Own       Name          Status          Owner Information
%1  *   10.0.1.1:1224:v9 Terminated                               
%2  *   10.0.1.2:2888:v9 Terminated        
}}}

'''Step 8. Exit from REPY

{{{
#!python
john@browsegood !> exit
}}}

Help command helps you look up the commands you can use in repy.                  

[[BR]]
==== 1-1.3. Testing programs in the interactive mode. ====
----

Instead of executing this program from the command line in batch mode, you could enter and run the code in interactive mode.

Although Repy doesn't have the interactive mode, and uses different function names from regular python, you can test only simple function operations in the interactive mode.

{{{
#!python
% python

>>> print “Hello, World”

Hello, World

>>>
}}}

While in interactive mode, you can test your simple code before executing and look up the command history by using the arrow keys.
To exit interactive mode, hit ctrl-d on Unix or ctrl-z on Windows. 

[[BR]]
=== A Hello World example (example 1.2) ===
----

In this example, we'll wait for the user to browse a port we listen on.   When the user browses our page, we'll display a hello world webpage and then exit.   Create a file "helloworldwebpage.py" with the following text:

{{{
#!python
def hello(ip,port,sockobj, thiscommhandle,listencommhandle):
{'fraction_non_alphanumeric': 0.08443513548893834, 'fraction_numerical': 0.01387616180128289, 'mean_word_length': 3.7720174890693317, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 18, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1499437', 'n_tokens_mistral': 2178, 'n_tokens_neox': 2078, 'n_words': 1145}