ParityPartTwo

Archive/LipstickOnAPigExceptionHierarchy.md

@@ -1,9 +1,9 @@
-# Lipstick on a Pig Exception Hierarchy Proposal
+# Lipstick on a Pig Exception Hierarchy Proposal
 
 
-## Overview / Purpose
+## Overview / Purpose
 
-The [wiki:Archive/LipstickOnAPig Lipstick on a Pig] strike force is attempting to create a standard exception hierarchy for repy to provide a unified method to allow users to handle exceptions within repy programs.
+The [Lipstick on a Pig](LipstickOnAPig.md) strike force is attempting to create a standard exception hierarchy for repy to provide a unified method to allow users to handle exceptions within repy programs.
 
 Currently the Repy library has inconsistent treatment and use of exceptions, which can be confusing and off-putting for new users. Our goal is to come up with a clear, uniform and logical way to present exceptions. The repy library functions have specific needs and goals, and the reflection hierarchy we're proposing reflects this. We are focusing on creating the core exception hierarchy which will be used by the repy library calls themselves; exceptions specific to any seattlelib code will need to augment the hierarchy with their own exceptions. 
 
@@ -15,9 +15,9 @@ The hierarchy we designed is meant to account for the specific types of errors w
 
 ----
 
-
 
-## Proposed Repy Hierarchy
+
+## Proposed Repy Hierarchy
 ----
 
 Below is our proposed exception hierarchy. The RepyException tree is separate from Exception to show how the two are meant to be distinct, although RepyException is a subclass of Python's Exception. 
@@ -53,21 +53,21 @@ PythonException
  +-- Builtin exceptions raised due to programmer mistakes (AttributeError, IndexError, NameError, etc)
 ```
 
-
 
-## Comparison to Python and Current Repy Implementation
+
+## Comparison to Python and Current Repy Implementation
 ----
 
  The python builtins tend to throw the same types of errors, and repy is meant to mimic this behavior. For example, builtins overwhelmingly raise ```TypeError``` when passed an argument of the wrong type, and raise ```ValueError``` when passed an incorrect value (such as a positive number instead of a negative one). 
 
  Repy exceptions are also meant to be less cryptic than some of the python exceptions. The socket.* errors for example were quite cryptic for new users, which resulted in the creation of ```AddressError``` rather than using python's ```socket.gaierror```.
 
-
 
-### Reused Python Exceptions
+
+### Reused Python Exceptions
 ----
 
-#### TypeError
+#### TypeError
 The python library uses [TypeError](http://docs.python.org/library/exceptions.html#exceptions.TypeError) to notify users that an argument of the wrong type was passed to a function. We want to emulate this behavior, as the current repy implementation primarily raises ```Exception``` and gives the description of what argument was incorrect.
 
 For example, the python ```abs``` built-in expects a numeric type. If a string is passed in, it raises a ```TypeError```. 
@@ -76,7 +76,7 @@ Similar behaviour is proposed for repy. For example, if a user tries specifying
 
 
 
-#### ValueError
+#### ValueError
 We want to change the Repy Library to emulate python's builtin API's usage of [ValueError](http://docs.python.org/library/exceptions.html#exceptions.ValueError). Although exact Python behavior differs per implementation and per call (a bad thing, in our opinion) ```ValueError``` tends to be used to indicate that a value of the correct type was passed in, but an invalid value was used. 
 
 An example of this is the ```sleep``` API call, which expects a numeric value greater than 0. If a negative number is passed in, a ValueError should be raised
@@ -105,9 +105,9 @@ socket.gethostbyname_ex("")
 ```
 While this could be considered a network error, it seems reasonable to assume that getting host information from the empty string is obviously a value error, no network checks have to be performed. The repy version of the above code should raise a ```ValueError```
 
-
 
-### Network Examples
+
+### Network Examples
 ----
 
 Network failures can be of particular importance given the nature of repy and the types of programs that tend to get written in it. There are a large number of reasons for why network operations can fail, and we feel python's socket module's interface could be improved upon. 
@@ -116,7 +116,7 @@ Native python's exception types for network related errors are pretty limited. T
 
 Our goal is to make it easy for users to determine precisely what went wrong with a network call, and be able to recover gracefully from these error conditions. 
 
-#### Host Name Example
+#### Host Name Example
 In native python, socket errors are defined in the socket module. Since repy has no concept of modules, and doesn't allow imports, it doesn't make sense to use the code snippet below.
 ```python
 import socket
@@ -137,7 +137,7 @@ except NetworkAddressError:
   #recover from error
 ```
 
-#### NetworkAddressError
+#### NetworkAddressError
   One class of errors that users may tend to see often due to the nature of resolution is address errors. In Python these are presented as ```socket.gaierror```, and what the specific cause of the problem is presented in the text of the exception. 
 
   Currently several repy network API calls still make use of ```socket.*``` errors. However the socket module is not in the scope of repy user programs, and modules aren't allowed to be imported. This means the current implementation of repy requires workarounds:
@@ -167,7 +167,7 @@ except NetworkError:
   #handle error condition
 ```
 
-#### Connection Example
+#### Connection Example
 The way of interacting with sockets is also different from regular python:
 
 ```python
@@ -200,7 +200,7 @@ finally:
 
 The exception handing for both cases are meant to be similar. We aimed to keep the programming model familiar enough to programmers with a python background, but also more user friendly to those just staring out with repy. Just as ```openconn``` and ```sendmess``` provide easy access for users to interact over networks, ```NetworkError``` and its subclasses are meant to facilitate convenient handling of common errors that can occur.
 
-#### ConnectionRefusedError
+#### ConnectionRefusedError
 In python, the following code snippet raises a ```socket.error```:
 ```python
 import socket
@@ -217,24 +217,24 @@ s = openconn('127.0.0.1', 12347, '127.0.0.1', 12345)
 #a ConnectionRefusedError would be raised
 ```
 
-#### NetworkDisconnectedError
+#### NetworkDisconnectedError
 This error is meant to be raised by ```getmyip()```, to indicate that a computer lost it's connection to the internet. The current behavior is ambiguous; ```getmyip``` raises a ```socket.gairerror``` with the message No address associated with hostname". 
 
 This error should also be raised if the socket layer raises ```socket.error``` 101: "Network is unreachable". This is currently the exception that is thrown by various network API calls, such as when ```sendmess``` is given an external ip but the network is disconnected
 
 
 
 
-
 
-### File System Examples
+
+### File System Examples
 ----
 
 While the python standard library provides many functions to flexibly interface with the underlying file system, the nature of repy requires a much more restricted subset of allowed operations. Additionally, there are a number of areas (such as file system modes) where the python standard library functions fail "silently" by either not raising an exception or proceeding with unexpected behavior. 
 
 The goal of the repy file system exceptions are to make it very clear what error has occurred and to not silently continue.
 
-#### File Open Examples
+#### File Open Examples
 
 In native python, most errors with the file system raise a general "IOError" with more specific details in the message. This makes it hard to realize what happened:
 
@@ -257,7 +257,7 @@ except FileNotFoundError:
   pass
 ```
 
-#### File Open Mode Example
+#### File Open Mode Example
 
 Python "silently" allows some obscure modes with the file system:
 
@@ -278,7 +278,7 @@ except InvalidFileModeException:
   pass
 ```
 
-#### Illegal File Names
+#### Illegal File Names
 
 Python allows many characters within the open method such as ".." to traverse directories. Because Repy has no concept of "directories" for programs running in the VMs, it must be more restrictive of allowed file names.
 
@@ -299,9 +299,9 @@ except IllegalFileNameException:
   pass
 ```
 
-
 
-### Resource Errors
+
+### Resource Errors
 ----
 
 Given the nature of repy, it is necessary to be able to signal users that they have exceeded their allowed resources. There are several types of resources, and some of these errors may be recoverable, some may not. For example, when a program is consuming too much memory, there is no way for a program to catch that exception. However, if a user tries to have too many files open or have too many event handlers at once, it will be possible to catch the exception raised during the attempt to create more, and allow the programmer to take appropriate action. 
@@ -310,9 +310,9 @@ Recoverable resource errors generally fall into two categories: attempting to us
 
 When trying to use a resource that wasn't permitted in a VMl's restrictions file, a ResourceNotAllowedError will be raised. In the case of overusing a resource, a ResourceExhaustedError will be raised. These will make it more clear why an error occured when trying to use a node's resources, and avoid the hacky string parsing currently required for recovery. 
 
-
 
-## Internal Errors
+
+## Internal Errors
 ----
 
 The above errors are meant to be the exceptions exposed to users. If a corrupt internal state is detected by repy, an ```InternalError``` will be raised. When this occurs, a user's repy program will terminate instantly. The rationale behind this is that we want to hide potential repy weaknesses to typical users, and ensure that a corrupt VM doesn't resume execution in a potentially harmful state. 
@@ -324,12 +324,12 @@ If this occurs in a ```try...finally``` block, the finally block will not get ex
 Information regarding the internal error will get privately logged, to provide seattle developers some insight regarding what caused the problem, and do postmortem analysis.
 
 
-
 
-## Unresolved Questions/Issues
+
+## Unresolved Questions/Issues
 ----
 
 There are a number of problems/questions we weren't sure the most appropriate way to handle. We'd appreciate any feedback regarding these issues
  * What type of error should be raised if a user's IP address changes? If a program has event handlers associated with an IP address and that changes, how should the user be notified?
    * The biggest concern for changing IP's is how to notify the user. It's easy to imagine the scenario where the only thing keeping a program in execution (rather than terminating) is event handlers waiting to be triggered. So if a program has a recvmess handler waiting to receive UDP packets, but the machine's IP changes, how do we notify the user in a meaningful way? If there's no context to which allow them to catch an exception we raised, does it even make sense to? Plus, recvmess is provided a localip, which is no longer valid! It's conceivable that users would write their own logic to periodically check the IP, and if it changes, then to update the event handlers accordingly. As to how/if repy should detect these (and possibly unregister stale listeners) is still uncertain...
- * Should an exception should be thrown if the interface and destination IP don't match?   I.e. ```sendmess("google.com",80, "hi", "127.0.0.1", 12345)```
+ * Should an exception should be thrown if the interface and destination IP don't match?   I.e. ```sendmess("google.com",80, "hi", "127.0.0.1", 12345)```

Contributing/BuildInstructions.md

@@ -69,6 +69,13 @@ directory which will be created as a sub-directory inside your main
 repository. It takes its instructions from `config_initialize.txt` to 
 fetch the dependencies.
 
+Make sure that you are using python 2.7 for initializing and building to
+avoid any errors with building. To use python 2.7, you can do:
+
+```sh
+$ python2 initialize.py
+```
+
 3. To build a runnable component from the source dependencies, run the 
 `scripts/build.py` script. You may supply it an optional target folder for 
 the build (which must be created first). Name this folder as you like.